1 @node Arithmetic, Date and Time, Mathematics, Top
2 @c %MENU% Low level arithmetic functions
3 @chapter Arithmetic Functions
5 This chapter contains information about functions for doing basic
6 arithmetic operations, such as splitting a float into its integer and
7 fractional parts or retrieving the imaginary part of a complex value.
8 These functions are declared in the header files @file{math.h} and
12 * Integers:: Basic integer types and concepts
13 * Integer Division:: Integer division with guaranteed rounding.
14 * Floating Point Numbers:: Basic concepts. IEEE 754.
15 * Floating Point Classes:: The five kinds of floating-point number.
16 * Floating Point Errors:: When something goes wrong in a calculation.
17 * Rounding:: Controlling how results are rounded.
18 * Control Functions:: Saving and restoring the FPU's state.
19 * Arithmetic Functions:: Fundamental operations provided by the library.
20 * Complex Numbers:: The types. Writing complex constants.
21 * Operations on Complex:: Projection, conjugation, decomposition.
22 * Parsing of Numbers:: Converting strings to numbers.
23 * System V Number Conversion:: An archaic way to convert numbers to strings.
30 The C language defines several integer data types: integer, short integer,
31 long integer, and character, all in both signed and unsigned varieties.
32 The GNU C compiler extends the language to contain long long integers
36 The C integer types were intended to allow code to be portable among
37 machines with different inherent data sizes (word sizes), so each type
38 may have different ranges on different machines. The problem with
39 this is that a program often needs to be written for a particular range
40 of integers, and sometimes must be written for a particular size of
41 storage, regardless of what machine the program runs on.
43 To address this problem, @theglibc{} contains C type definitions
44 you can use to declare integers that meet your exact needs. Because the
45 @glibcadj{} header files are customized to a specific machine, your
46 program source code doesn't have to be.
48 These @code{typedef}s are in @file{stdint.h}.
51 If you require that an integer be represented in exactly N bits, use one
52 of the following types, with the obvious mapping to bit size and signedness:
65 If your C compiler and target machine do not allow integers of a certain
66 size, the corresponding above type does not exist.
68 If you don't need a specific storage size, but want the smallest data
69 structure with @emph{at least} N bits, use one of these:
82 If you don't need a specific storage size, but want the data structure
83 that allows the fastest access while having at least N bits (and
84 among data structures with the same access speed, the smallest one), use
98 If you want an integer with the widest range possible on the platform on
99 which it is being used, use one of the following. If you use these,
100 you should write code that takes into account the variable size and range
108 @Theglibc{} also provides macros that tell you the maximum and
109 minimum possible values for each integer data type. The macro names
110 follow these examples: @code{INT32_MAX}, @code{UINT8_MAX},
111 @code{INT_FAST32_MIN}, @code{INT_LEAST64_MIN}, @code{UINTMAX_MAX},
112 @code{INTMAX_MAX}, @code{INTMAX_MIN}. Note that there are no macros for
113 unsigned integer minima. These are always zero.
114 @cindex maximum possible integer
115 @cindex minimum possible integer
117 There are similar macros for use with C's built in integer types which
118 should come with your C compiler. These are described in @ref{Data Type
121 Don't forget you can use the C @code{sizeof} function with any of these
122 data types to get the number of bytes of storage each uses.
125 @node Integer Division
126 @section Integer Division
127 @cindex integer division functions
129 This section describes functions for performing integer division. These
130 functions are redundant when GNU CC is used, because in GNU C the
131 @samp{/} operator always rounds towards zero. But in other C
132 implementations, @samp{/} may round differently with negative arguments.
133 @code{div} and @code{ldiv} are useful because they specify how to round
134 the quotient: towards zero. The remainder has the same sign as the
137 These functions are specified to return a result @var{r} such that the value
138 @code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
142 To use these facilities, you should include the header file
143 @file{stdlib.h} in your program.
147 @deftp {Data Type} div_t
148 This is a structure type used to hold the result returned by the @code{div}
149 function. It has the following members:
153 The quotient from the division.
156 The remainder from the division.
162 @deftypefun div_t div (int @var{numerator}, int @var{denominator})
163 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
164 @c Functions in this section are pure, and thus safe.
165 This function @code{div} computes the quotient and remainder from
166 the division of @var{numerator} by @var{denominator}, returning the
167 result in a structure of type @code{div_t}.
169 If the result cannot be represented (as in a division by zero), the
170 behavior is undefined.
172 Here is an example, albeit not a very useful one.
176 result = div (20, -6);
180 Now @code{result.quot} is @code{-3} and @code{result.rem} is @code{2}.
185 @deftp {Data Type} ldiv_t
186 This is a structure type used to hold the result returned by the @code{ldiv}
187 function. It has the following members:
191 The quotient from the division.
194 The remainder from the division.
197 (This is identical to @code{div_t} except that the components are of
198 type @code{long int} rather than @code{int}.)
203 @deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
204 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
205 The @code{ldiv} function is similar to @code{div}, except that the
206 arguments are of type @code{long int} and the result is returned as a
207 structure of type @code{ldiv_t}.
212 @deftp {Data Type} lldiv_t
213 This is a structure type used to hold the result returned by the @code{lldiv}
214 function. It has the following members:
217 @item long long int quot
218 The quotient from the division.
220 @item long long int rem
221 The remainder from the division.
224 (This is identical to @code{div_t} except that the components are of
225 type @code{long long int} rather than @code{int}.)
230 @deftypefun lldiv_t lldiv (long long int @var{numerator}, long long int @var{denominator})
231 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
232 The @code{lldiv} function is like the @code{div} function, but the
233 arguments are of type @code{long long int} and the result is returned as
234 a structure of type @code{lldiv_t}.
236 The @code{lldiv} function was added in @w{ISO C99}.
241 @deftp {Data Type} imaxdiv_t
242 This is a structure type used to hold the result returned by the @code{imaxdiv}
243 function. It has the following members:
247 The quotient from the division.
250 The remainder from the division.
253 (This is identical to @code{div_t} except that the components are of
254 type @code{intmax_t} rather than @code{int}.)
256 See @ref{Integers} for a description of the @code{intmax_t} type.
262 @deftypefun imaxdiv_t imaxdiv (intmax_t @var{numerator}, intmax_t @var{denominator})
263 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
264 The @code{imaxdiv} function is like the @code{div} function, but the
265 arguments are of type @code{intmax_t} and the result is returned as
266 a structure of type @code{imaxdiv_t}.
268 See @ref{Integers} for a description of the @code{intmax_t} type.
270 The @code{imaxdiv} function was added in @w{ISO C99}.
274 @node Floating Point Numbers
275 @section Floating Point Numbers
276 @cindex floating point
278 @cindex IEEE floating point
280 Most computer hardware has support for two different kinds of numbers:
281 integers (@math{@dots{}-3, -2, -1, 0, 1, 2, 3@dots{}}) and
282 floating-point numbers. Floating-point numbers have three parts: the
283 @dfn{mantissa}, the @dfn{exponent}, and the @dfn{sign bit}. The real
284 number represented by a floating-point value is given by
286 $(s \mathrel? -1 \mathrel: 1) \cdot 2^e \cdot M$
289 @math{(s ? -1 : 1) @mul{} 2^e @mul{} M}
291 where @math{s} is the sign bit, @math{e} the exponent, and @math{M}
292 the mantissa. @xref{Floating Point Concepts}, for details. (It is
293 possible to have a different @dfn{base} for the exponent, but all modern
294 hardware uses @math{2}.)
296 Floating-point numbers can represent a finite subset of the real
297 numbers. While this subset is large enough for most purposes, it is
298 important to remember that the only reals that can be represented
299 exactly are rational numbers that have a terminating binary expansion
300 shorter than the width of the mantissa. Even simple fractions such as
301 @math{1/5} can only be approximated by floating point.
303 Mathematical operations and functions frequently need to produce values
304 that are not representable. Often these values can be approximated
305 closely enough for practical purposes, but sometimes they can't.
306 Historically there was no way to tell when the results of a calculation
307 were inaccurate. Modern computers implement the @w{IEEE 754} standard
308 for numerical computations, which defines a framework for indicating to
309 the program when the results of calculation are not trustworthy. This
310 framework consists of a set of @dfn{exceptions} that indicate why a
311 result could not be represented, and the special values @dfn{infinity}
312 and @dfn{not a number} (NaN).
314 @node Floating Point Classes
315 @section Floating-Point Number Classification Functions
316 @cindex floating-point classes
317 @cindex classes, floating-point
320 @w{ISO C99} defines macros that let you determine what sort of
321 floating-point number a variable holds.
325 @deftypefn {Macro} int fpclassify (@emph{float-type} @var{x})
326 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
327 This is a generic macro which works on all floating-point types and
328 which returns a value of type @code{int}. The possible values are:
332 The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
335 The value of @var{x} is either plus or minus infinity (@pxref{Infinity
338 The value of @var{x} is zero. In floating-point formats like @w{IEEE
339 754}, where zero can be signed, this value is also returned if
340 @var{x} is negative zero.
342 Numbers whose absolute value is too small to be represented in the
343 normal format are represented in an alternate, @dfn{denormalized} format
344 (@pxref{Floating Point Concepts}). This format is less precise but can
345 represent values closer to zero. @code{fpclassify} returns this value
346 for values of @var{x} in this alternate format.
348 This value is returned for all other values of @var{x}. It indicates
349 that there is nothing special about the number.
354 @code{fpclassify} is most useful if more than one property of a number
355 must be tested. There are more specific macros which only test one
356 property at a time. Generally these macros execute faster than
357 @code{fpclassify}, since there is special hardware support for them.
358 You should therefore use the specific macros whenever possible.
362 @deftypefn {Macro} int isfinite (@emph{float-type} @var{x})
363 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
364 This macro returns a nonzero value if @var{x} is finite: not plus or
365 minus infinity, and not NaN. It is equivalent to
368 (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
371 @code{isfinite} is implemented as a macro which accepts any
377 @deftypefn {Macro} int isnormal (@emph{float-type} @var{x})
378 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
379 This macro returns a nonzero value if @var{x} is finite and normalized.
383 (fpclassify (x) == FP_NORMAL)
389 @deftypefn {Macro} int isnan (@emph{float-type} @var{x})
390 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
391 This macro returns a nonzero value if @var{x} is NaN. It is equivalent
395 (fpclassify (x) == FP_NAN)
401 @deftypefn {Macro} int issignaling (@emph{float-type} @var{x})
402 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
403 This macro returns a nonzero value if @var{x} is a signaling NaN
404 (sNaN). It is based on draft TS 18661 and currently enabled as a GNU
408 Another set of floating-point classification functions was provided by
409 BSD. @Theglibc{} also supports these functions; however, we
410 recommend that you use the ISO C99 macros in new code. Those are standard
411 and will be available more widely. Also, since they are macros, you do
412 not have to worry about the type of their argument.
416 @deftypefun int isinf (double @var{x})
419 @deftypefunx int isinff (float @var{x})
422 @deftypefunx int isinfl (long double @var{x})
423 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
424 This function returns @code{-1} if @var{x} represents negative infinity,
425 @code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
430 @deftypefun int isnan (double @var{x})
433 @deftypefunx int isnanf (float @var{x})
436 @deftypefunx int isnanl (long double @var{x})
437 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
438 This function returns a nonzero value if @var{x} is a ``not a number''
439 value, and zero otherwise.
441 @strong{NB:} The @code{isnan} macro defined by @w{ISO C99} overrides
442 the BSD function. This is normally not a problem, because the two
443 routines behave identically. However, if you really need to get the BSD
444 function for some reason, you can write
453 @deftypefun int finite (double @var{x})
456 @deftypefunx int finitef (float @var{x})
459 @deftypefunx int finitel (long double @var{x})
460 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
461 This function returns a nonzero value if @var{x} is finite or a ``not a
462 number'' value, and zero otherwise.
465 @strong{Portability Note:} The functions listed in this section are BSD
469 @node Floating Point Errors
470 @section Errors in Floating-Point Calculations
473 * FP Exceptions:: IEEE 754 math exceptions and how to detect them.
474 * Infinity and NaN:: Special values returned by calculations.
475 * Status bit operations:: Checking for exceptions after the fact.
476 * Math Error Reporting:: How the math functions report errors.
480 @subsection FP Exceptions
484 @cindex division by zero
485 @cindex inexact exception
486 @cindex invalid exception
487 @cindex overflow exception
488 @cindex underflow exception
490 The @w{IEEE 754} standard defines five @dfn{exceptions} that can occur
491 during a calculation. Each corresponds to a particular sort of error,
494 When exceptions occur (when exceptions are @dfn{raised}, in the language
495 of the standard), one of two things can happen. By default the
496 exception is simply noted in the floating-point @dfn{status word}, and
497 the program continues as if nothing had happened. The operation
498 produces a default value, which depends on the exception (see the table
499 below). Your program can check the status word to find out which
502 Alternatively, you can enable @dfn{traps} for exceptions. In that case,
503 when an exception is raised, your program will receive the @code{SIGFPE}
504 signal. The default action for this signal is to terminate the
505 program. @xref{Signal Handling}, for how you can change the effect of
509 In the System V math library, the user-defined function @code{matherr}
510 is called when certain exceptions occur inside math library functions.
511 However, the Unix98 standard deprecates this interface. We support it
512 for historical compatibility, but recommend that you do not use it in
513 new programs. When this interface is used, exceptions may not be
517 The exceptions defined in @w{IEEE 754} are:
520 @item Invalid Operation
521 This exception is raised if the given operands are invalid for the
522 operation to be performed. Examples are
523 (see @w{IEEE 754}, @w{section 7}):
526 Addition or subtraction: @math{@infinity{} - @infinity{}}. (But
527 @math{@infinity{} + @infinity{} = @infinity{}}).
529 Multiplication: @math{0 @mul{} @infinity{}}.
531 Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
533 Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
536 Square root if the operand is less then zero. More generally, any
537 mathematical function evaluated outside its domain produces this
540 Conversion of a floating-point number to an integer or decimal
541 string, when the number cannot be represented in the target format (due
542 to overflow, infinity, or NaN).
544 Conversion of an unrecognizable input string.
546 Comparison via predicates involving @math{<} or @math{>}, when one or
547 other of the operands is NaN. You can prevent this exception by using
548 the unordered comparison functions instead; see @ref{FP Comparison Functions}.
551 If the exception does not trap, the result of the operation is NaN.
553 @item Division by Zero
554 This exception is raised when a finite nonzero number is divided
555 by zero. If no trap occurs the result is either @math{+@infinity{}} or
556 @math{-@infinity{}}, depending on the signs of the operands.
559 This exception is raised whenever the result cannot be represented
560 as a finite value in the precision format of the destination. If no trap
561 occurs the result depends on the sign of the intermediate result and the
562 current rounding mode (@w{IEEE 754}, @w{section 7.3}):
565 Round to nearest carries all overflows to @math{@infinity{}}
566 with the sign of the intermediate result.
568 Round toward @math{0} carries all overflows to the largest representable
569 finite number with the sign of the intermediate result.
571 Round toward @math{-@infinity{}} carries positive overflows to the
572 largest representable finite number and negative overflows to
576 Round toward @math{@infinity{}} carries negative overflows to the
577 most negative representable finite number and positive overflows
578 to @math{@infinity{}}.
581 Whenever the overflow exception is raised, the inexact exception is also
585 The underflow exception is raised when an intermediate result is too
586 small to be calculated accurately, or if the operation's result rounded
587 to the destination precision is too small to be normalized.
589 When no trap is installed for the underflow exception, underflow is
590 signaled (via the underflow flag) only when both tininess and loss of
591 accuracy have been detected. If no trap handler is installed the
592 operation continues with an imprecise small value, or zero if the
593 destination precision cannot hold the small exact result.
596 This exception is signalled if a rounded result is not exact (such as
597 when calculating the square root of two) or a result overflows without
601 @node Infinity and NaN
602 @subsection Infinity and NaN
607 @w{IEEE 754} floating point numbers can represent positive or negative
608 infinity, and @dfn{NaN} (not a number). These three values arise from
609 calculations whose result is undefined or cannot be represented
610 accurately. You can also deliberately set a floating-point variable to
611 any of them, which is sometimes useful. Some examples of calculations
612 that produce infinity or NaN:
616 @math{1/0 = @infinity{}}
617 @math{log (0) = -@infinity{}}
618 @math{sqrt (-1) = NaN}
622 $${1\over0} = \infty$$
624 $$\sqrt{-1} = \hbox{NaN}$$
627 When a calculation produces any of these values, an exception also
628 occurs; see @ref{FP Exceptions}.
630 The basic operations and math functions all accept infinity and NaN and
631 produce sensible output. Infinities propagate through calculations as
632 one would expect: for example, @math{2 + @infinity{} = @infinity{}},
633 @math{4/@infinity{} = 0}, atan @math{(@infinity{}) = @pi{}/2}. NaN, on
634 the other hand, infects any calculation that involves it. Unless the
635 calculation would produce the same result no matter what real value
636 replaced NaN, the result is NaN.
638 In comparison operations, positive infinity is larger than all values
639 except itself and NaN, and negative infinity is smaller than all values
640 except itself and NaN. NaN is @dfn{unordered}: it is not equal to,
641 greater than, or less than anything, @emph{including itself}. @code{x ==
642 x} is false if the value of @code{x} is NaN. You can use this to test
643 whether a value is NaN or not, but the recommended way to test for NaN
644 is with the @code{isnan} function (@pxref{Floating Point Classes}). In
645 addition, @code{<}, @code{>}, @code{<=}, and @code{>=} will raise an
646 exception when applied to NaNs.
648 @file{math.h} defines macros that allow you to explicitly set a variable
653 @deftypevr Macro float INFINITY
654 An expression representing positive infinity. It is equal to the value
655 produced by mathematical operations like @code{1.0 / 0.0}.
656 @code{-INFINITY} represents negative infinity.
658 You can test whether a floating-point value is infinite by comparing it
659 to this macro. However, this is not recommended; you should use the
660 @code{isfinite} macro instead. @xref{Floating Point Classes}.
662 This macro was introduced in the @w{ISO C99} standard.
667 @deftypevr Macro float NAN
668 An expression representing a value which is ``not a number''. This
669 macro is a GNU extension, available only on machines that support the
670 ``not a number'' value---that is to say, on all machines that support
673 You can use @samp{#ifdef NAN} to test whether the machine supports
674 NaN. (Of course, you must arrange for GNU extensions to be visible,
675 such as by defining @code{_GNU_SOURCE}, and then you must include
679 @w{IEEE 754} also allows for another unusual value: negative zero. This
680 value is produced when you divide a positive number by negative
681 infinity, or when a negative result is smaller than the limits of
684 @node Status bit operations
685 @subsection Examining the FPU status word
687 @w{ISO C99} defines functions to query and manipulate the
688 floating-point status word. You can use these functions to check for
689 untrapped exceptions when it's convenient, rather than worrying about
690 them in the middle of a calculation.
692 These constants represent the various @w{IEEE 754} exceptions. Not all
693 FPUs report all the different exceptions. Each constant is defined if
694 and only if the FPU you are compiling for supports that exception, so
695 you can test for FPU support with @samp{#ifdef}. They are defined in
702 The inexact exception.
706 The divide by zero exception.
710 The underflow exception.
714 The overflow exception.
718 The invalid exception.
721 The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
722 which are supported by the FP implementation.
724 These functions allow you to clear exception flags, test for exceptions,
725 and save and restore the set of exceptions flagged.
729 @deftypefun int feclearexcept (int @var{excepts})
730 @safety{@prelim{}@mtsafe{}@assafe{@assposix{}}@acsafe{@acsposix{}}}
731 @c The other functions in this section that modify FP status register
732 @c mostly do so with non-atomic load-modify-store sequences, but since
733 @c the register is thread-specific, this should be fine, and safe for
734 @c cancellation. As long as the FP environment is restored before the
735 @c signal handler returns control to the interrupted thread (like any
736 @c kernel should do), the functions are also safe for use in signal
738 This function clears all of the supported exception flags indicated by
741 The function returns zero in case the operation was successful, a
742 non-zero value otherwise.
747 @deftypefun int feraiseexcept (int @var{excepts})
748 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
749 This function raises the supported exceptions indicated by
750 @var{excepts}. If more than one exception bit in @var{excepts} is set
751 the order in which the exceptions are raised is undefined except that
752 overflow (@code{FE_OVERFLOW}) or underflow (@code{FE_UNDERFLOW}) are
753 raised before inexact (@code{FE_INEXACT}). Whether for overflow or
754 underflow the inexact exception is also raised is also implementation
757 The function returns zero in case the operation was successful, a
758 non-zero value otherwise.
763 @deftypefun int fetestexcept (int @var{excepts})
764 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
765 Test whether the exception flags indicated by the parameter @var{except}
766 are currently set. If any of them are, a nonzero value is returned
767 which specifies which exceptions are set. Otherwise the result is zero.
770 To understand these functions, imagine that the status word is an
771 integer variable named @var{status}. @code{feclearexcept} is then
772 equivalent to @samp{status &= ~excepts} and @code{fetestexcept} is
773 equivalent to @samp{(status & excepts)}. The actual implementation may
774 be very different, of course.
776 Exception flags are only cleared when the program explicitly requests it,
777 by calling @code{feclearexcept}. If you want to check for exceptions
778 from a set of calculations, you should clear all the flags first. Here
779 is a simple example of the way to use @code{fetestexcept}:
785 feclearexcept (FE_ALL_EXCEPT);
787 raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
788 if (raised & FE_OVERFLOW) @{ /* @dots{} */ @}
789 if (raised & FE_INVALID) @{ /* @dots{} */ @}
794 You cannot explicitly set bits in the status word. You can, however,
795 save the entire status word and restore it later. This is done with the
800 @deftypefun int fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
801 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
802 This function stores in the variable pointed to by @var{flagp} an
803 implementation-defined value representing the current setting of the
804 exception flags indicated by @var{excepts}.
806 The function returns zero in case the operation was successful, a
807 non-zero value otherwise.
812 @deftypefun int fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
813 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
814 This function restores the flags for the exceptions indicated by
815 @var{excepts} to the values stored in the variable pointed to by
818 The function returns zero in case the operation was successful, a
819 non-zero value otherwise.
822 Note that the value stored in @code{fexcept_t} bears no resemblance to
823 the bit mask returned by @code{fetestexcept}. The type may not even be
824 an integer. Do not attempt to modify an @code{fexcept_t} variable.
826 @node Math Error Reporting
827 @subsection Error Reporting by Mathematical Functions
828 @cindex errors, mathematical
832 Many of the math functions are defined only over a subset of the real or
833 complex numbers. Even if they are mathematically defined, their result
834 may be larger or smaller than the range representable by their return
835 type without loss of accuracy. These are known as @dfn{domain errors},
837 @dfn{underflows}, respectively. Math functions do several things when
838 one of these errors occurs. In this manual we will refer to the
839 complete response as @dfn{signalling} a domain error, overflow, or
842 When a math function suffers a domain error, it raises the invalid
843 exception and returns NaN. It also sets @var{errno} to @code{EDOM};
844 this is for compatibility with old systems that do not support @w{IEEE
845 754} exception handling. Likewise, when overflow occurs, math
846 functions raise the overflow exception and, in the default rounding
847 mode, return @math{@infinity{}} or @math{-@infinity{}} as appropriate
848 (in other rounding modes, the largest finite value of the appropriate
849 sign is returned when appropriate for that rounding mode). They also
850 set @var{errno} to @code{ERANGE} if returning @math{@infinity{}} or
851 @math{-@infinity{}}; @var{errno} may or may not be set to
852 @code{ERANGE} when a finite value is returned on overflow. When
853 underflow occurs, the underflow exception is raised, and zero
854 (appropriately signed) or a subnormal value, as appropriate for the
855 mathematical result of the function and the rounding mode, is
856 returned. @var{errno} may be set to @code{ERANGE}, but this is not
857 guaranteed; it is intended that @theglibc{} should set it when the
858 underflow is to an appropriately signed zero, but not necessarily for
861 Some of the math functions are defined mathematically to result in a
862 complex value over parts of their domains. The most familiar example of
863 this is taking the square root of a negative number. The complex math
864 functions, such as @code{csqrt}, will return the appropriate complex value
865 in this case. The real-valued functions, such as @code{sqrt}, will
866 signal a domain error.
868 Some older hardware does not support infinities. On that hardware,
869 overflows instead return a particular very large number (usually the
870 largest representable number). @file{math.h} defines macros you can use
871 to test for overflow on both old and new hardware.
875 @deftypevr Macro double HUGE_VAL
878 @deftypevrx Macro float HUGE_VALF
881 @deftypevrx Macro {long double} HUGE_VALL
882 An expression representing a particular very large number. On machines
883 that use @w{IEEE 754} floating point format, @code{HUGE_VAL} is infinity.
884 On other machines, it's typically the largest positive number that can
887 Mathematical functions return the appropriately typed version of
888 @code{HUGE_VAL} or @code{@minus{}HUGE_VAL} when the result is too large
893 @section Rounding Modes
895 Floating-point calculations are carried out internally with extra
896 precision, and then rounded to fit into the destination type. This
897 ensures that results are as precise as the input data. @w{IEEE 754}
898 defines four possible rounding modes:
901 @item Round to nearest.
902 This is the default mode. It should be used unless there is a specific
903 need for one of the others. In this mode results are rounded to the
904 nearest representable value. If the result is midway between two
905 representable values, the even representable is chosen. @dfn{Even} here
906 means the lowest-order bit is zero. This rounding mode prevents
907 statistical bias and guarantees numeric stability: round-off errors in a
908 lengthy calculation will remain smaller than half of @code{FLT_EPSILON}.
910 @c @item Round toward @math{+@infinity{}}
911 @item Round toward plus Infinity.
912 All results are rounded to the smallest representable value
913 which is greater than the result.
915 @c @item Round toward @math{-@infinity{}}
916 @item Round toward minus Infinity.
917 All results are rounded to the largest representable value which is less
920 @item Round toward zero.
921 All results are rounded to the largest representable value whose
922 magnitude is less than that of the result. In other words, if the
923 result is negative it is rounded up; if it is positive, it is rounded
928 @file{fenv.h} defines constants which you can use to refer to the
929 various rounding modes. Each one will be defined if and only if the FPU
930 supports the corresponding rounding mode.
943 Round toward @math{+@infinity{}}.
949 Round toward @math{-@infinity{}}.
953 @vindex FE_TOWARDZERO
958 Underflow is an unusual case. Normally, @w{IEEE 754} floating point
959 numbers are always normalized (@pxref{Floating Point Concepts}).
960 Numbers smaller than @math{2^r} (where @math{r} is the minimum exponent,
961 @code{FLT_MIN_RADIX-1} for @var{float}) cannot be represented as
962 normalized numbers. Rounding all such numbers to zero or @math{2^r}
963 would cause some algorithms to fail at 0. Therefore, they are left in
964 denormalized form. That produces loss of precision, since some bits of
965 the mantissa are stolen to indicate the decimal point.
967 If a result is too small to be represented as a denormalized number, it
968 is rounded to zero. However, the sign of the result is preserved; if
969 the calculation was negative, the result is @dfn{negative zero}.
970 Negative zero can also result from some operations on infinity, such as
971 @math{4/-@infinity{}}.
973 At any time one of the above four rounding modes is selected. You can
974 find out which one with this function:
978 @deftypefun int fegetround (void)
979 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
980 Returns the currently selected rounding mode, represented by one of the
981 values of the defined rounding mode macros.
985 To change the rounding mode, use this function:
989 @deftypefun int fesetround (int @var{round})
990 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
991 Changes the currently selected rounding mode to @var{round}. If
992 @var{round} does not correspond to one of the supported rounding modes
993 nothing is changed. @code{fesetround} returns zero if it changed the
994 rounding mode, a nonzero value if the mode is not supported.
997 You should avoid changing the rounding mode if possible. It can be an
998 expensive operation; also, some hardware requires you to compile your
999 program differently for it to work. The resulting code may run slower.
1000 See your compiler documentation for details.
1001 @c This section used to claim that functions existed to round one number
1002 @c in a specific fashion. I can't find any functions in the library
1003 @c that do that. -zw
1005 @node Control Functions
1006 @section Floating-Point Control Functions
1008 @w{IEEE 754} floating-point implementations allow the programmer to
1009 decide whether traps will occur for each of the exceptions, by setting
1010 bits in the @dfn{control word}. In C, traps result in the program
1011 receiving the @code{SIGFPE} signal; see @ref{Signal Handling}.
1013 @strong{NB:} @w{IEEE 754} says that trap handlers are given details of
1014 the exceptional situation, and can set the result value. C signals do
1015 not provide any mechanism to pass this information back and forth.
1016 Trapping exceptions in C is therefore not very useful.
1018 It is sometimes necessary to save the state of the floating-point unit
1019 while you perform some calculation. The library provides functions
1020 which save and restore the exception flags, the set of exceptions that
1021 generate traps, and the rounding mode. This information is known as the
1022 @dfn{floating-point environment}.
1024 The functions to save and restore the floating-point environment all use
1025 a variable of type @code{fenv_t} to store information. This type is
1026 defined in @file{fenv.h}. Its size and contents are
1027 implementation-defined. You should not attempt to manipulate a variable
1028 of this type directly.
1030 To save the state of the FPU, use one of these functions:
1034 @deftypefun int fegetenv (fenv_t *@var{envp})
1035 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1036 Store the floating-point environment in the variable pointed to by
1039 The function returns zero in case the operation was successful, a
1040 non-zero value otherwise.
1045 @deftypefun int feholdexcept (fenv_t *@var{envp})
1046 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1047 Store the current floating-point environment in the object pointed to by
1048 @var{envp}. Then clear all exception flags, and set the FPU to trap no
1049 exceptions. Not all FPUs support trapping no exceptions; if
1050 @code{feholdexcept} cannot set this mode, it returns nonzero value. If it
1051 succeeds, it returns zero.
1054 The functions which restore the floating-point environment can take these
1059 Pointers to @code{fenv_t} objects, which were initialized previously by a
1060 call to @code{fegetenv} or @code{feholdexcept}.
1063 The special macro @code{FE_DFL_ENV} which represents the floating-point
1064 environment as it was available at program start.
1066 Implementation defined macros with names starting with @code{FE_} and
1067 having type @code{fenv_t *}.
1069 @vindex FE_NOMASK_ENV
1070 If possible, @theglibc{} defines a macro @code{FE_NOMASK_ENV}
1071 which represents an environment where every exception raised causes a
1072 trap to occur. You can test for this macro using @code{#ifdef}. It is
1073 only defined if @code{_GNU_SOURCE} is defined.
1075 Some platforms might define other predefined environments.
1079 To set the floating-point environment, you can use either of these
1084 @deftypefun int fesetenv (const fenv_t *@var{envp})
1085 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1086 Set the floating-point environment to that described by @var{envp}.
1088 The function returns zero in case the operation was successful, a
1089 non-zero value otherwise.
1094 @deftypefun int feupdateenv (const fenv_t *@var{envp})
1095 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1096 Like @code{fesetenv}, this function sets the floating-point environment
1097 to that described by @var{envp}. However, if any exceptions were
1098 flagged in the status word before @code{feupdateenv} was called, they
1099 remain flagged after the call. In other words, after @code{feupdateenv}
1100 is called, the status word is the bitwise OR of the previous status word
1101 and the one saved in @var{envp}.
1103 The function returns zero in case the operation was successful, a
1104 non-zero value otherwise.
1108 To control for individual exceptions if raising them causes a trap to
1109 occur, you can use the following two functions.
1111 @strong{Portability Note:} These functions are all GNU extensions.
1115 @deftypefun int feenableexcept (int @var{excepts})
1116 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1117 This functions enables traps for each of the exceptions as indicated by
1118 the parameter @var{except}. The individual exceptions are described in
1119 @ref{Status bit operations}. Only the specified exceptions are
1120 enabled, the status of the other exceptions is not changed.
1122 The function returns the previous enabled exceptions in case the
1123 operation was successful, @code{-1} otherwise.
1128 @deftypefun int fedisableexcept (int @var{excepts})
1129 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1130 This functions disables traps for each of the exceptions as indicated by
1131 the parameter @var{except}. The individual exceptions are described in
1132 @ref{Status bit operations}. Only the specified exceptions are
1133 disabled, the status of the other exceptions is not changed.
1135 The function returns the previous enabled exceptions in case the
1136 operation was successful, @code{-1} otherwise.
1141 @deftypefun int fegetexcept (void)
1142 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1143 The function returns a bitmask of all currently enabled exceptions. It
1144 returns @code{-1} in case of failure.
1147 @node Arithmetic Functions
1148 @section Arithmetic Functions
1150 The C library provides functions to do basic operations on
1151 floating-point numbers. These include absolute value, maximum and minimum,
1152 normalization, bit twiddling, rounding, and a few others.
1155 * Absolute Value:: Absolute values of integers and floats.
1156 * Normalization Functions:: Extracting exponents and putting them back.
1157 * Rounding Functions:: Rounding floats to integers.
1158 * Remainder Functions:: Remainders on division, precisely defined.
1159 * FP Bit Twiddling:: Sign bit adjustment. Adding epsilon.
1160 * FP Comparison Functions:: Comparisons without risk of exceptions.
1161 * Misc FP Arithmetic:: Max, min, positive difference, multiply-add.
1164 @node Absolute Value
1165 @subsection Absolute Value
1166 @cindex absolute value functions
1168 These functions are provided for obtaining the @dfn{absolute value} (or
1169 @dfn{magnitude}) of a number. The absolute value of a real number
1170 @var{x} is @var{x} if @var{x} is positive, @minus{}@var{x} if @var{x} is
1171 negative. For a complex number @var{z}, whose real part is @var{x} and
1172 whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
1173 (@var{x}*@var{x} + @var{y}*@var{y})}}.
1177 Prototypes for @code{abs}, @code{labs} and @code{llabs} are in @file{stdlib.h};
1178 @code{imaxabs} is declared in @file{inttypes.h};
1179 @code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h}.
1180 @code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
1184 @deftypefun int abs (int @var{number})
1187 @deftypefunx {long int} labs (long int @var{number})
1190 @deftypefunx {long long int} llabs (long long int @var{number})
1193 @deftypefunx intmax_t imaxabs (intmax_t @var{number})
1194 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1195 These functions return the absolute value of @var{number}.
1197 Most computers use a two's complement integer representation, in which
1198 the absolute value of @code{INT_MIN} (the smallest possible @code{int})
1199 cannot be represented; thus, @w{@code{abs (INT_MIN)}} is not defined.
1201 @code{llabs} and @code{imaxdiv} are new to @w{ISO C99}.
1203 See @ref{Integers} for a description of the @code{intmax_t} type.
1209 @deftypefun double fabs (double @var{number})
1212 @deftypefunx float fabsf (float @var{number})
1215 @deftypefunx {long double} fabsl (long double @var{number})
1216 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1217 This function returns the absolute value of the floating-point number
1223 @deftypefun double cabs (complex double @var{z})
1226 @deftypefunx float cabsf (complex float @var{z})
1229 @deftypefunx {long double} cabsl (complex long double @var{z})
1230 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1231 These functions return the absolute value of the complex number @var{z}
1232 (@pxref{Complex Numbers}). The absolute value of a complex number is:
1235 sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
1238 This function should always be used instead of the direct formula
1239 because it takes special care to avoid losing precision. It may also
1240 take advantage of hardware support for this operation. See @code{hypot}
1241 in @ref{Exponents and Logarithms}.
1244 @node Normalization Functions
1245 @subsection Normalization Functions
1246 @cindex normalization functions (floating-point)
1248 The functions described in this section are primarily provided as a way
1249 to efficiently perform certain low-level manipulations on floating point
1250 numbers that are represented internally using a binary radix;
1251 see @ref{Floating Point Concepts}. These functions are required to
1252 have equivalent behavior even if the representation does not use a radix
1253 of 2, but of course they are unlikely to be particularly efficient in
1257 All these functions are declared in @file{math.h}.
1261 @deftypefun double frexp (double @var{value}, int *@var{exponent})
1264 @deftypefunx float frexpf (float @var{value}, int *@var{exponent})
1267 @deftypefunx {long double} frexpl (long double @var{value}, int *@var{exponent})
1268 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1269 These functions are used to split the number @var{value}
1270 into a normalized fraction and an exponent.
1272 If the argument @var{value} is not zero, the return value is @var{value}
1273 times a power of two, and its magnitude is always in the range 1/2
1274 (inclusive) to 1 (exclusive). The corresponding exponent is stored in
1275 @code{*@var{exponent}}; the return value multiplied by 2 raised to this
1276 exponent equals the original number @var{value}.
1278 For example, @code{frexp (12.8, &exponent)} returns @code{0.8} and
1279 stores @code{4} in @code{exponent}.
1281 If @var{value} is zero, then the return value is zero and
1282 zero is stored in @code{*@var{exponent}}.
1287 @deftypefun double ldexp (double @var{value}, int @var{exponent})
1290 @deftypefunx float ldexpf (float @var{value}, int @var{exponent})
1293 @deftypefunx {long double} ldexpl (long double @var{value}, int @var{exponent})
1294 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1295 These functions return the result of multiplying the floating-point
1296 number @var{value} by 2 raised to the power @var{exponent}. (It can
1297 be used to reassemble floating-point numbers that were taken apart
1300 For example, @code{ldexp (0.8, 4)} returns @code{12.8}.
1303 The following functions, which come from BSD, provide facilities
1304 equivalent to those of @code{ldexp} and @code{frexp}. See also the
1305 @w{ISO C} function @code{logb} which originally also appeared in BSD.
1309 @deftypefun double scalb (double @var{value}, double @var{exponent})
1312 @deftypefunx float scalbf (float @var{value}, float @var{exponent})
1315 @deftypefunx {long double} scalbl (long double @var{value}, long double @var{exponent})
1316 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1317 The @code{scalb} function is the BSD name for @code{ldexp}.
1322 @deftypefun double scalbn (double @var{x}, int @var{n})
1325 @deftypefunx float scalbnf (float @var{x}, int @var{n})
1328 @deftypefunx {long double} scalbnl (long double @var{x}, int @var{n})
1329 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1330 @code{scalbn} is identical to @code{scalb}, except that the exponent
1331 @var{n} is an @code{int} instead of a floating-point number.
1336 @deftypefun double scalbln (double @var{x}, long int @var{n})
1339 @deftypefunx float scalblnf (float @var{x}, long int @var{n})
1342 @deftypefunx {long double} scalblnl (long double @var{x}, long int @var{n})
1343 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1344 @code{scalbln} is identical to @code{scalb}, except that the exponent
1345 @var{n} is a @code{long int} instead of a floating-point number.
1350 @deftypefun double significand (double @var{x})
1353 @deftypefunx float significandf (float @var{x})
1356 @deftypefunx {long double} significandl (long double @var{x})
1357 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1358 @code{significand} returns the mantissa of @var{x} scaled to the range
1360 It is equivalent to @w{@code{scalb (@var{x}, (double) -ilogb (@var{x}))}}.
1362 This function exists mainly for use in certain standardized tests
1363 of @w{IEEE 754} conformance.
1366 @node Rounding Functions
1367 @subsection Rounding Functions
1368 @cindex converting floats to integers
1371 The functions listed here perform operations such as rounding and
1372 truncation of floating-point values. Some of these functions convert
1373 floating point numbers to integer values. They are all declared in
1376 You can also convert floating-point numbers to integers simply by
1377 casting them to @code{int}. This discards the fractional part,
1378 effectively rounding towards zero. However, this only works if the
1379 result can actually be represented as an @code{int}---for very large
1380 numbers, this is impossible. The functions listed here return the
1381 result as a @code{double} instead to get around this problem.
1385 @deftypefun double ceil (double @var{x})
1388 @deftypefunx float ceilf (float @var{x})
1391 @deftypefunx {long double} ceill (long double @var{x})
1392 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1393 These functions round @var{x} upwards to the nearest integer,
1394 returning that value as a @code{double}. Thus, @code{ceil (1.5)}
1400 @deftypefun double floor (double @var{x})
1403 @deftypefunx float floorf (float @var{x})
1406 @deftypefunx {long double} floorl (long double @var{x})
1407 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1408 These functions round @var{x} downwards to the nearest
1409 integer, returning that value as a @code{double}. Thus, @code{floor
1410 (1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
1415 @deftypefun double trunc (double @var{x})
1418 @deftypefunx float truncf (float @var{x})
1421 @deftypefunx {long double} truncl (long double @var{x})
1422 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1423 The @code{trunc} functions round @var{x} towards zero to the nearest
1424 integer (returned in floating-point format). Thus, @code{trunc (1.5)}
1425 is @code{1.0} and @code{trunc (-1.5)} is @code{-1.0}.
1430 @deftypefun double rint (double @var{x})
1433 @deftypefunx float rintf (float @var{x})
1436 @deftypefunx {long double} rintl (long double @var{x})
1437 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1438 These functions round @var{x} to an integer value according to the
1439 current rounding mode. @xref{Floating Point Parameters}, for
1440 information about the various rounding modes. The default
1441 rounding mode is to round to the nearest integer; some machines
1442 support other modes, but round-to-nearest is always used unless
1443 you explicitly select another.
1445 If @var{x} was not initially an integer, these functions raise the
1451 @deftypefun double nearbyint (double @var{x})
1454 @deftypefunx float nearbyintf (float @var{x})
1457 @deftypefunx {long double} nearbyintl (long double @var{x})
1458 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1459 These functions return the same value as the @code{rint} functions, but
1460 do not raise the inexact exception if @var{x} is not an integer.
1465 @deftypefun double round (double @var{x})
1468 @deftypefunx float roundf (float @var{x})
1471 @deftypefunx {long double} roundl (long double @var{x})
1472 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1473 These functions are similar to @code{rint}, but they round halfway
1474 cases away from zero instead of to the nearest integer (or other
1475 current rounding mode).
1480 @deftypefun {long int} lrint (double @var{x})
1483 @deftypefunx {long int} lrintf (float @var{x})
1486 @deftypefunx {long int} lrintl (long double @var{x})
1487 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1488 These functions are just like @code{rint}, but they return a
1489 @code{long int} instead of a floating-point number.
1494 @deftypefun {long long int} llrint (double @var{x})
1497 @deftypefunx {long long int} llrintf (float @var{x})
1500 @deftypefunx {long long int} llrintl (long double @var{x})
1501 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1502 These functions are just like @code{rint}, but they return a
1503 @code{long long int} instead of a floating-point number.
1508 @deftypefun {long int} lround (double @var{x})
1511 @deftypefunx {long int} lroundf (float @var{x})
1514 @deftypefunx {long int} lroundl (long double @var{x})
1515 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1516 These functions are just like @code{round}, but they return a
1517 @code{long int} instead of a floating-point number.
1522 @deftypefun {long long int} llround (double @var{x})
1525 @deftypefunx {long long int} llroundf (float @var{x})
1528 @deftypefunx {long long int} llroundl (long double @var{x})
1529 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1530 These functions are just like @code{round}, but they return a
1531 @code{long long int} instead of a floating-point number.
1537 @deftypefun double modf (double @var{value}, double *@var{integer-part})
1540 @deftypefunx float modff (float @var{value}, float *@var{integer-part})
1543 @deftypefunx {long double} modfl (long double @var{value}, long double *@var{integer-part})
1544 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1545 These functions break the argument @var{value} into an integer part and a
1546 fractional part (between @code{-1} and @code{1}, exclusive). Their sum
1547 equals @var{value}. Each of the parts has the same sign as @var{value},
1548 and the integer part is always rounded toward zero.
1550 @code{modf} stores the integer part in @code{*@var{integer-part}}, and
1551 returns the fractional part. For example, @code{modf (2.5, &intpart)}
1552 returns @code{0.5} and stores @code{2.0} into @code{intpart}.
1555 @node Remainder Functions
1556 @subsection Remainder Functions
1558 The functions in this section compute the remainder on division of two
1559 floating-point numbers. Each is a little different; pick the one that
1564 @deftypefun double fmod (double @var{numerator}, double @var{denominator})
1567 @deftypefunx float fmodf (float @var{numerator}, float @var{denominator})
1570 @deftypefunx {long double} fmodl (long double @var{numerator}, long double @var{denominator})
1571 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1572 These functions compute the remainder from the division of
1573 @var{numerator} by @var{denominator}. Specifically, the return value is
1574 @code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
1575 is the quotient of @var{numerator} divided by @var{denominator}, rounded
1576 towards zero to an integer. Thus, @w{@code{fmod (6.5, 2.3)}} returns
1577 @code{1.9}, which is @code{6.5} minus @code{4.6}.
1579 The result has the same sign as the @var{numerator} and has magnitude
1580 less than the magnitude of the @var{denominator}.
1582 If @var{denominator} is zero, @code{fmod} signals a domain error.
1587 @deftypefun double drem (double @var{numerator}, double @var{denominator})
1590 @deftypefunx float dremf (float @var{numerator}, float @var{denominator})
1593 @deftypefunx {long double} dreml (long double @var{numerator}, long double @var{denominator})
1594 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1595 These functions are like @code{fmod} except that they round the
1596 internal quotient @var{n} to the nearest integer instead of towards zero
1597 to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
1598 which is @code{6.5} minus @code{6.9}.
1600 The absolute value of the result is less than or equal to half the
1601 absolute value of the @var{denominator}. The difference between
1602 @code{fmod (@var{numerator}, @var{denominator})} and @code{drem
1603 (@var{numerator}, @var{denominator})} is always either
1604 @var{denominator}, minus @var{denominator}, or zero.
1606 If @var{denominator} is zero, @code{drem} signals a domain error.
1611 @deftypefun double remainder (double @var{numerator}, double @var{denominator})
1614 @deftypefunx float remainderf (float @var{numerator}, float @var{denominator})
1617 @deftypefunx {long double} remainderl (long double @var{numerator}, long double @var{denominator})
1618 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1619 This function is another name for @code{drem}.
1622 @node FP Bit Twiddling
1623 @subsection Setting and modifying single bits of FP values
1624 @cindex FP arithmetic
1626 There are some operations that are too complicated or expensive to
1627 perform by hand on floating-point numbers. @w{ISO C99} defines
1628 functions to do these operations, which mostly involve changing single
1633 @deftypefun double copysign (double @var{x}, double @var{y})
1636 @deftypefunx float copysignf (float @var{x}, float @var{y})
1639 @deftypefunx {long double} copysignl (long double @var{x}, long double @var{y})
1640 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1641 These functions return @var{x} but with the sign of @var{y}. They work
1642 even if @var{x} or @var{y} are NaN or zero. Both of these can carry a
1643 sign (although not all implementations support it) and this is one of
1644 the few operations that can tell the difference.
1646 @code{copysign} never raises an exception.
1647 @c except signalling NaNs
1649 This function is defined in @w{IEC 559} (and the appendix with
1650 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
1655 @deftypefun int signbit (@emph{float-type} @var{x})
1656 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1657 @code{signbit} is a generic macro which can work on all floating-point
1658 types. It returns a nonzero value if the value of @var{x} has its sign
1661 This is not the same as @code{x < 0.0}, because @w{IEEE 754} floating
1662 point allows zero to be signed. The comparison @code{-0.0 < 0.0} is
1663 false, but @code{signbit (-0.0)} will return a nonzero value.
1668 @deftypefun double nextafter (double @var{x}, double @var{y})
1671 @deftypefunx float nextafterf (float @var{x}, float @var{y})
1674 @deftypefunx {long double} nextafterl (long double @var{x}, long double @var{y})
1675 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1676 The @code{nextafter} function returns the next representable neighbor of
1677 @var{x} in the direction towards @var{y}. The size of the step between
1678 @var{x} and the result depends on the type of the result. If
1679 @math{@var{x} = @var{y}} the function simply returns @var{y}. If either
1680 value is @code{NaN}, @code{NaN} is returned. Otherwise
1681 a value corresponding to the value of the least significant bit in the
1682 mantissa is added or subtracted, depending on the direction.
1683 @code{nextafter} will signal overflow or underflow if the result goes
1684 outside of the range of normalized numbers.
1686 This function is defined in @w{IEC 559} (and the appendix with
1687 recommended functions in @w{IEEE 754}/@w{IEEE 854}).
1692 @deftypefun double nexttoward (double @var{x}, long double @var{y})
1695 @deftypefunx float nexttowardf (float @var{x}, long double @var{y})
1698 @deftypefunx {long double} nexttowardl (long double @var{x}, long double @var{y})
1699 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1700 These functions are identical to the corresponding versions of
1701 @code{nextafter} except that their second argument is a @code{long
1707 @deftypefun double nextup (double @var{x})
1710 @deftypefunx float nextupf (float @var{x})
1713 @deftypefunx {long double} nextupl (long double @var{x})
1714 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1715 The @code{nextup} function returns the next representable neighbor of @var{x}
1716 in the direction of positive infinity. If @var{x} is the smallest negative
1717 subnormal number in the type of @var{x} the function returns @code{-0}. If
1718 @math{@var{x} = @code{0}} the function returns the smallest positive subnormal
1719 number in the type of @var{x}. If @var{x} is NaN, NaN is returned.
1720 If @var{x} is @math{+@infinity{}}, @math{+@infinity{}} is returned.
1721 @code{nextup} is based on TS 18661 and currently enabled as a GNU extension.
1722 @code{nextup} never raises an exception except for signaling NaNs.
1727 @deftypefun double nextdown (double @var{x})
1730 @deftypefunx float nextdownf (float @var{x})
1733 @deftypefunx {long double} nextdownl (long double @var{x})
1734 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1735 The @code{nextdown} function returns the next representable neighbor of @var{x}
1736 in the direction of negative infinity. If @var{x} is the smallest positive
1737 subnormal number in the type of @var{x} the function returns @code{+0}. If
1738 @math{@var{x} = @code{0}} the function returns the smallest negative subnormal
1739 number in the type of @var{x}. If @var{x} is NaN, NaN is returned.
1740 If @var{x} is @math{-@infinity{}}, @math{-@infinity{}} is returned.
1741 @code{nextdown} is based on TS 18661 and currently enabled as a GNU extension.
1742 @code{nextdown} never raises an exception except for signaling NaNs.
1748 @deftypefun double nan (const char *@var{tagp})
1751 @deftypefunx float nanf (const char *@var{tagp})
1754 @deftypefunx {long double} nanl (const char *@var{tagp})
1755 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
1756 @c The unsafe-but-ruled-safe locale use comes from strtod.
1757 The @code{nan} function returns a representation of NaN, provided that
1758 NaN is supported by the target platform.
1759 @code{nan ("@var{n-char-sequence}")} is equivalent to
1760 @code{strtod ("NAN(@var{n-char-sequence})")}.
1762 The argument @var{tagp} is used in an unspecified manner. On @w{IEEE
1763 754} systems, there are many representations of NaN, and @var{tagp}
1764 selects one. On other systems it may do nothing.
1767 @node FP Comparison Functions
1768 @subsection Floating-Point Comparison Functions
1769 @cindex unordered comparison
1771 The standard C comparison operators provoke exceptions when one or other
1772 of the operands is NaN. For example,
1779 will raise an exception if @var{a} is NaN. (This does @emph{not}
1780 happen with @code{==} and @code{!=}; those merely return false and true,
1781 respectively, when NaN is examined.) Frequently this exception is
1782 undesirable. @w{ISO C99} therefore defines comparison functions that
1783 do not raise exceptions when NaN is examined. All of the functions are
1784 implemented as macros which allow their arguments to be of any
1785 floating-point type. The macros are guaranteed to evaluate their
1786 arguments only once.
1790 @deftypefn Macro int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1791 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1792 This macro determines whether the argument @var{x} is greater than
1793 @var{y}. It is equivalent to @code{(@var{x}) > (@var{y})}, but no
1794 exception is raised if @var{x} or @var{y} are NaN.
1799 @deftypefn Macro int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1800 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1801 This macro determines whether the argument @var{x} is greater than or
1802 equal to @var{y}. It is equivalent to @code{(@var{x}) >= (@var{y})}, but no
1803 exception is raised if @var{x} or @var{y} are NaN.
1808 @deftypefn Macro int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1809 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1810 This macro determines whether the argument @var{x} is less than @var{y}.
1811 It is equivalent to @code{(@var{x}) < (@var{y})}, but no exception is
1812 raised if @var{x} or @var{y} are NaN.
1817 @deftypefn Macro int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1818 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1819 This macro determines whether the argument @var{x} is less than or equal
1820 to @var{y}. It is equivalent to @code{(@var{x}) <= (@var{y})}, but no
1821 exception is raised if @var{x} or @var{y} are NaN.
1826 @deftypefn Macro int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1827 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1828 This macro determines whether the argument @var{x} is less or greater
1829 than @var{y}. It is equivalent to @code{(@var{x}) < (@var{y}) ||
1830 (@var{x}) > (@var{y})} (although it only evaluates @var{x} and @var{y}
1831 once), but no exception is raised if @var{x} or @var{y} are NaN.
1833 This macro is not equivalent to @code{@var{x} != @var{y}}, because that
1834 expression is true if @var{x} or @var{y} are NaN.
1839 @deftypefn Macro int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
1840 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1841 This macro determines whether its arguments are unordered. In other
1842 words, it is true if @var{x} or @var{y} are NaN, and false otherwise.
1845 Not all machines provide hardware support for these operations. On
1846 machines that don't, the macros can be very slow. Therefore, you should
1847 not use these functions when NaN is not a concern.
1849 @strong{NB:} There are no macros @code{isequal} or @code{isunequal}.
1850 They are unnecessary, because the @code{==} and @code{!=} operators do
1851 @emph{not} throw an exception if one or both of the operands are NaN.
1853 @node Misc FP Arithmetic
1854 @subsection Miscellaneous FP arithmetic functions
1857 @cindex positive difference
1858 @cindex multiply-add
1860 The functions in this section perform miscellaneous but common
1861 operations that are awkward to express with C operators. On some
1862 processors these functions can use special machine instructions to
1863 perform these operations faster than the equivalent C code.
1867 @deftypefun double fmin (double @var{x}, double @var{y})
1870 @deftypefunx float fminf (float @var{x}, float @var{y})
1873 @deftypefunx {long double} fminl (long double @var{x}, long double @var{y})
1874 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1875 The @code{fmin} function returns the lesser of the two values @var{x}
1876 and @var{y}. It is similar to the expression
1878 ((x) < (y) ? (x) : (y))
1880 except that @var{x} and @var{y} are only evaluated once.
1882 If an argument is NaN, the other argument is returned. If both arguments
1883 are NaN, NaN is returned.
1888 @deftypefun double fmax (double @var{x}, double @var{y})
1891 @deftypefunx float fmaxf (float @var{x}, float @var{y})
1894 @deftypefunx {long double} fmaxl (long double @var{x}, long double @var{y})
1895 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1896 The @code{fmax} function returns the greater of the two values @var{x}
1899 If an argument is NaN, the other argument is returned. If both arguments
1900 are NaN, NaN is returned.
1905 @deftypefun double fdim (double @var{x}, double @var{y})
1908 @deftypefunx float fdimf (float @var{x}, float @var{y})
1911 @deftypefunx {long double} fdiml (long double @var{x}, long double @var{y})
1912 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1913 The @code{fdim} function returns the positive difference between
1914 @var{x} and @var{y}. The positive difference is @math{@var{x} -
1915 @var{y}} if @var{x} is greater than @var{y}, and @math{0} otherwise.
1917 If @var{x}, @var{y}, or both are NaN, NaN is returned.
1922 @deftypefun double fma (double @var{x}, double @var{y}, double @var{z})
1925 @deftypefunx float fmaf (float @var{x}, float @var{y}, float @var{z})
1928 @deftypefunx {long double} fmal (long double @var{x}, long double @var{y}, long double @var{z})
1930 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1931 The @code{fma} function performs floating-point multiply-add. This is
1932 the operation @math{(@var{x} @mul{} @var{y}) + @var{z}}, but the
1933 intermediate result is not rounded to the destination type. This can
1934 sometimes improve the precision of a calculation.
1936 This function was introduced because some processors have a special
1937 instruction to perform multiply-add. The C compiler cannot use it
1938 directly, because the expression @samp{x*y + z} is defined to round the
1939 intermediate result. @code{fma} lets you choose when you want to round
1943 On processors which do not implement multiply-add in hardware,
1944 @code{fma} can be very slow since it must avoid intermediate rounding.
1945 @file{math.h} defines the symbols @code{FP_FAST_FMA},
1946 @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} when the corresponding
1947 version of @code{fma} is no slower than the expression @samp{x*y + z}.
1948 In @theglibc{}, this always means the operation is implemented in
1952 @node Complex Numbers
1953 @section Complex Numbers
1955 @cindex complex numbers
1957 @w{ISO C99} introduces support for complex numbers in C. This is done
1958 with a new type qualifier, @code{complex}. It is a keyword if and only
1959 if @file{complex.h} has been included. There are three complex types,
1960 corresponding to the three real types: @code{float complex},
1961 @code{double complex}, and @code{long double complex}.
1963 To construct complex numbers you need a way to indicate the imaginary
1964 part of a number. There is no standard notation for an imaginary
1965 floating point constant. Instead, @file{complex.h} defines two macros
1966 that can be used to create complex numbers.
1968 @deftypevr Macro {const float complex} _Complex_I
1969 This macro is a representation of the complex number ``@math{0+1i}''.
1970 Multiplying a real floating-point value by @code{_Complex_I} gives a
1971 complex number whose value is purely imaginary. You can use this to
1972 construct complex constants:
1975 @math{3.0 + 4.0i} = @code{3.0 + 4.0 * _Complex_I}
1978 Note that @code{_Complex_I * _Complex_I} has the value @code{-1}, but
1979 the type of that value is @code{complex}.
1982 @c Put this back in when gcc supports _Imaginary_I. It's too confusing.
1985 Without an optimizing compiler this is more expensive than the use of
1986 @code{_Imaginary_I} but with is better than nothing. You can avoid all
1987 the hassles if you use the @code{I} macro below if the name is not
1990 @deftypevr Macro {const float imaginary} _Imaginary_I
1991 This macro is a representation of the value ``@math{1i}''. I.e., it is
1995 _Imaginary_I * _Imaginary_I = -1
1999 The result is not of type @code{float imaginary} but instead @code{float}.
2000 One can use it to easily construct complex number like in
2003 3.0 - _Imaginary_I * 4.0
2007 which results in the complex number with a real part of 3.0 and a
2008 imaginary part -4.0.
2013 @code{_Complex_I} is a bit of a mouthful. @file{complex.h} also defines
2014 a shorter name for the same constant.
2016 @deftypevr Macro {const float complex} I
2017 This macro has exactly the same value as @code{_Complex_I}. Most of the
2018 time it is preferable. However, it causes problems if you want to use
2019 the identifier @code{I} for something else. You can safely write
2022 #include <complex.h>
2027 if you need @code{I} for your own purposes. (In that case we recommend
2028 you also define some other short name for @code{_Complex_I}, such as
2032 If the implementation does not support the @code{imaginary} types
2033 @code{I} is defined as @code{_Complex_I} which is the second best
2034 solution. It still can be used in the same way but requires a most
2035 clever compiler to get the same results.
2039 @node Operations on Complex
2040 @section Projections, Conjugates, and Decomposing of Complex Numbers
2041 @cindex project complex numbers
2042 @cindex conjugate complex numbers
2043 @cindex decompose complex numbers
2046 @w{ISO C99} also defines functions that perform basic operations on
2047 complex numbers, such as decomposition and conjugation. The prototypes
2048 for all these functions are in @file{complex.h}. All functions are
2049 available in three variants, one for each of the three complex types.
2053 @deftypefun double creal (complex double @var{z})
2056 @deftypefunx float crealf (complex float @var{z})
2059 @deftypefunx {long double} creall (complex long double @var{z})
2060 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2061 These functions return the real part of the complex number @var{z}.
2066 @deftypefun double cimag (complex double @var{z})
2069 @deftypefunx float cimagf (complex float @var{z})
2072 @deftypefunx {long double} cimagl (complex long double @var{z})
2073 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2074 These functions return the imaginary part of the complex number @var{z}.
2079 @deftypefun {complex double} conj (complex double @var{z})
2082 @deftypefunx {complex float} conjf (complex float @var{z})
2085 @deftypefunx {complex long double} conjl (complex long double @var{z})
2086 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2087 These functions return the conjugate value of the complex number
2088 @var{z}. The conjugate of a complex number has the same real part and a
2089 negated imaginary part. In other words, @samp{conj(a + bi) = a + -bi}.
2094 @deftypefun double carg (complex double @var{z})
2097 @deftypefunx float cargf (complex float @var{z})
2100 @deftypefunx {long double} cargl (complex long double @var{z})
2101 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2102 These functions return the argument of the complex number @var{z}.
2103 The argument of a complex number is the angle in the complex plane
2104 between the positive real axis and a line passing through zero and the
2105 number. This angle is measured in the usual fashion and ranges from
2106 @math{-@pi{}} to @math{@pi{}}.
2108 @code{carg} has a branch cut along the negative real axis.
2113 @deftypefun {complex double} cproj (complex double @var{z})
2116 @deftypefunx {complex float} cprojf (complex float @var{z})
2119 @deftypefunx {complex long double} cprojl (complex long double @var{z})
2120 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2121 These functions return the projection of the complex value @var{z} onto
2122 the Riemann sphere. Values with an infinite imaginary part are projected
2123 to positive infinity on the real axis, even if the real part is NaN. If
2124 the real part is infinite, the result is equivalent to
2127 INFINITY + I * copysign (0.0, cimag (z))
2131 @node Parsing of Numbers
2132 @section Parsing of Numbers
2133 @cindex parsing numbers (in formatted input)
2134 @cindex converting strings to numbers
2135 @cindex number syntax, parsing
2136 @cindex syntax, for reading numbers
2138 This section describes functions for ``reading'' integer and
2139 floating-point numbers from a string. It may be more convenient in some
2140 cases to use @code{sscanf} or one of the related functions; see
2141 @ref{Formatted Input}. But often you can make a program more robust by
2142 finding the tokens in the string by hand, then converting the numbers
2146 * Parsing of Integers:: Functions for conversion of integer values.
2147 * Parsing of Floats:: Functions for conversion of floating-point
2151 @node Parsing of Integers
2152 @subsection Parsing of Integers
2156 The @samp{str} functions are declared in @file{stdlib.h} and those
2157 beginning with @samp{wcs} are declared in @file{wchar.h}. One might
2158 wonder about the use of @code{restrict} in the prototypes of the
2159 functions in this section. It is seemingly useless but the @w{ISO C}
2160 standard uses it (for the functions defined there) so we have to do it
2165 @deftypefun {long int} strtol (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2166 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2167 @c strtol uses the thread-local pointer to the locale in effect, and
2168 @c strtol_l loads the LC_NUMERIC locale data from it early on and once,
2169 @c but if the locale is the global locale, and another thread calls
2170 @c setlocale in a way that modifies the pointer to the LC_CTYPE locale
2171 @c category, the behavior of e.g. IS*, TOUPPER will vary throughout the
2172 @c execution of the function, because they re-read the locale data from
2173 @c the given locale pointer. We solved this by documenting setlocale as
2175 The @code{strtol} (``string-to-long'') function converts the initial
2176 part of @var{string} to a signed integer, which is returned as a value
2177 of type @code{long int}.
2179 This function attempts to decompose @var{string} as follows:
2183 A (possibly empty) sequence of whitespace characters. Which characters
2184 are whitespace is determined by the @code{isspace} function
2185 (@pxref{Classification of Characters}). These are discarded.
2188 An optional plus or minus sign (@samp{+} or @samp{-}).
2191 A nonempty sequence of digits in the radix specified by @var{base}.
2193 If @var{base} is zero, decimal radix is assumed unless the series of
2194 digits begins with @samp{0} (specifying octal radix), or @samp{0x} or
2195 @samp{0X} (specifying hexadecimal radix); in other words, the same
2196 syntax used for integer constants in C.
2198 Otherwise @var{base} must have a value between @code{2} and @code{36}.
2199 If @var{base} is @code{16}, the digits may optionally be preceded by
2200 @samp{0x} or @samp{0X}. If base has no legal value the value returned
2201 is @code{0l} and the global variable @code{errno} is set to @code{EINVAL}.
2204 Any remaining characters in the string. If @var{tailptr} is not a null
2205 pointer, @code{strtol} stores a pointer to this tail in
2206 @code{*@var{tailptr}}.
2209 If the string is empty, contains only whitespace, or does not contain an
2210 initial substring that has the expected syntax for an integer in the
2211 specified @var{base}, no conversion is performed. In this case,
2212 @code{strtol} returns a value of zero and the value stored in
2213 @code{*@var{tailptr}} is the value of @var{string}.
2215 In a locale other than the standard @code{"C"} locale, this function
2216 may recognize additional implementation-dependent syntax.
2218 If the string has valid syntax for an integer but the value is not
2219 representable because of overflow, @code{strtol} returns either
2220 @code{LONG_MAX} or @code{LONG_MIN} (@pxref{Range of Type}), as
2221 appropriate for the sign of the value. It also sets @code{errno}
2222 to @code{ERANGE} to indicate there was overflow.
2224 You should not check for errors by examining the return value of
2225 @code{strtol}, because the string might be a valid representation of
2226 @code{0l}, @code{LONG_MAX}, or @code{LONG_MIN}. Instead, check whether
2227 @var{tailptr} points to what you expect after the number
2228 (e.g. @code{'\0'} if the string should end after the number). You also
2229 need to clear @var{errno} before the call and check it afterward, in
2230 case there was overflow.
2232 There is an example at the end of this section.
2237 @deftypefun {long int} wcstol (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2238 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2239 The @code{wcstol} function is equivalent to the @code{strtol} function
2240 in nearly all aspects but handles wide character strings.
2242 The @code{wcstol} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2247 @deftypefun {unsigned long int} strtoul (const char *retrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2248 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2249 The @code{strtoul} (``string-to-unsigned-long'') function is like
2250 @code{strtol} except it converts to an @code{unsigned long int} value.
2251 The syntax is the same as described above for @code{strtol}. The value
2252 returned on overflow is @code{ULONG_MAX} (@pxref{Range of Type}).
2254 If @var{string} depicts a negative number, @code{strtoul} acts the same
2255 as @var{strtol} but casts the result to an unsigned integer. That means
2256 for example that @code{strtoul} on @code{"-1"} returns @code{ULONG_MAX}
2257 and an input more negative than @code{LONG_MIN} returns
2258 (@code{ULONG_MAX} + 1) / 2.
2260 @code{strtoul} sets @var{errno} to @code{EINVAL} if @var{base} is out of
2261 range, or @code{ERANGE} on overflow.
2266 @deftypefun {unsigned long int} wcstoul (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2267 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2268 The @code{wcstoul} function is equivalent to the @code{strtoul} function
2269 in nearly all aspects but handles wide character strings.
2271 The @code{wcstoul} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2276 @deftypefun {long long int} strtoll (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2277 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2278 The @code{strtoll} function is like @code{strtol} except that it returns
2279 a @code{long long int} value, and accepts numbers with a correspondingly
2282 If the string has valid syntax for an integer but the value is not
2283 representable because of overflow, @code{strtoll} returns either
2284 @code{LLONG_MAX} or @code{LLONG_MIN} (@pxref{Range of Type}), as
2285 appropriate for the sign of the value. It also sets @code{errno} to
2286 @code{ERANGE} to indicate there was overflow.
2288 The @code{strtoll} function was introduced in @w{ISO C99}.
2293 @deftypefun {long long int} wcstoll (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2294 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2295 The @code{wcstoll} function is equivalent to the @code{strtoll} function
2296 in nearly all aspects but handles wide character strings.
2298 The @code{wcstoll} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2303 @deftypefun {long long int} strtoq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2304 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2305 @code{strtoq} (``string-to-quad-word'') is the BSD name for @code{strtoll}.
2310 @deftypefun {long long int} wcstoq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2311 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2312 The @code{wcstoq} function is equivalent to the @code{strtoq} function
2313 in nearly all aspects but handles wide character strings.
2315 The @code{wcstoq} function is a GNU extension.
2320 @deftypefun {unsigned long long int} strtoull (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2321 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2322 The @code{strtoull} function is related to @code{strtoll} the same way
2323 @code{strtoul} is related to @code{strtol}.
2325 The @code{strtoull} function was introduced in @w{ISO C99}.
2330 @deftypefun {unsigned long long int} wcstoull (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2331 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2332 The @code{wcstoull} function is equivalent to the @code{strtoull} function
2333 in nearly all aspects but handles wide character strings.
2335 The @code{wcstoull} function was introduced in @w{Amendment 1} of @w{ISO C90}.
2340 @deftypefun {unsigned long long int} strtouq (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2341 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2342 @code{strtouq} is the BSD name for @code{strtoull}.
2347 @deftypefun {unsigned long long int} wcstouq (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2348 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2349 The @code{wcstouq} function is equivalent to the @code{strtouq} function
2350 in nearly all aspects but handles wide character strings.
2352 The @code{wcstouq} function is a GNU extension.
2357 @deftypefun intmax_t strtoimax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2358 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2359 The @code{strtoimax} function is like @code{strtol} except that it returns
2360 a @code{intmax_t} value, and accepts numbers of a corresponding range.
2362 If the string has valid syntax for an integer but the value is not
2363 representable because of overflow, @code{strtoimax} returns either
2364 @code{INTMAX_MAX} or @code{INTMAX_MIN} (@pxref{Integers}), as
2365 appropriate for the sign of the value. It also sets @code{errno} to
2366 @code{ERANGE} to indicate there was overflow.
2368 See @ref{Integers} for a description of the @code{intmax_t} type. The
2369 @code{strtoimax} function was introduced in @w{ISO C99}.
2374 @deftypefun intmax_t wcstoimax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2375 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2376 The @code{wcstoimax} function is equivalent to the @code{strtoimax} function
2377 in nearly all aspects but handles wide character strings.
2379 The @code{wcstoimax} function was introduced in @w{ISO C99}.
2384 @deftypefun uintmax_t strtoumax (const char *restrict @var{string}, char **restrict @var{tailptr}, int @var{base})
2385 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2386 The @code{strtoumax} function is related to @code{strtoimax}
2387 the same way that @code{strtoul} is related to @code{strtol}.
2389 See @ref{Integers} for a description of the @code{intmax_t} type. The
2390 @code{strtoumax} function was introduced in @w{ISO C99}.
2395 @deftypefun uintmax_t wcstoumax (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr}, int @var{base})
2396 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2397 The @code{wcstoumax} function is equivalent to the @code{strtoumax} function
2398 in nearly all aspects but handles wide character strings.
2400 The @code{wcstoumax} function was introduced in @w{ISO C99}.
2405 @deftypefun {long int} atol (const char *@var{string})
2406 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2407 This function is similar to the @code{strtol} function with a @var{base}
2408 argument of @code{10}, except that it need not detect overflow errors.
2409 The @code{atol} function is provided mostly for compatibility with
2410 existing code; using @code{strtol} is more robust.
2415 @deftypefun int atoi (const char *@var{string})
2416 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2417 This function is like @code{atol}, except that it returns an @code{int}.
2418 The @code{atoi} function is also considered obsolete; use @code{strtol}
2424 @deftypefun {long long int} atoll (const char *@var{string})
2425 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2426 This function is similar to @code{atol}, except it returns a @code{long
2429 The @code{atoll} function was introduced in @w{ISO C99}. It too is
2430 obsolete (despite having just been added); use @code{strtoll} instead.
2433 All the functions mentioned in this section so far do not handle
2434 alternative representations of characters as described in the locale
2435 data. Some locales specify thousands separator and the way they have to
2436 be used which can help to make large numbers more readable. To read
2437 such numbers one has to use the @code{scanf} functions with the @samp{'}
2440 Here is a function which parses a string as a sequence of integers and
2441 returns the sum of them:
2445 sum_ints_from_string (char *string)
2453 /* @r{Skip whitespace by hand, to detect the end.} */
2454 while (isspace (*string)) string++;
2458 /* @r{There is more nonwhitespace,} */
2459 /* @r{so it ought to be another number.} */
2462 next = strtol (string, &tail, 0);
2463 /* @r{Add it in, if not overflow.} */
2465 printf ("Overflow\n");
2468 /* @r{Advance past it.} */
2476 @node Parsing of Floats
2477 @subsection Parsing of Floats
2480 The @samp{str} functions are declared in @file{stdlib.h} and those
2481 beginning with @samp{wcs} are declared in @file{wchar.h}. One might
2482 wonder about the use of @code{restrict} in the prototypes of the
2483 functions in this section. It is seemingly useless but the @w{ISO C}
2484 standard uses it (for the functions defined there) so we have to do it
2489 @deftypefun double strtod (const char *restrict @var{string}, char **restrict @var{tailptr})
2490 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2491 @c Besides the unsafe-but-ruled-safe locale uses, this uses a lot of
2492 @c mpn, but it's all safe.
2495 @c get_rounding_mode ok
2499 @c MPN2FLOAT -> mpn_construct_(float|double|long_double) ok
2501 @c mpn_mul_1 -> umul_ppmm ok
2503 @c mpn_lshift_1 -> mpn_lshift ok
2507 @c STRNCASECMP ok, wide and narrow
2508 @c round_and_return ok
2514 @c count_leading_zeros ok
2519 The @code{strtod} (``string-to-double'') function converts the initial
2520 part of @var{string} to a floating-point number, which is returned as a
2521 value of type @code{double}.
2523 This function attempts to decompose @var{string} as follows:
2527 A (possibly empty) sequence of whitespace characters. Which characters
2528 are whitespace is determined by the @code{isspace} function
2529 (@pxref{Classification of Characters}). These are discarded.
2532 An optional plus or minus sign (@samp{+} or @samp{-}).
2534 @item A floating point number in decimal or hexadecimal format. The
2539 A nonempty sequence of digits optionally containing a decimal-point
2540 character---normally @samp{.}, but it depends on the locale
2541 (@pxref{General Numeric}).
2544 An optional exponent part, consisting of a character @samp{e} or
2545 @samp{E}, an optional sign, and a sequence of digits.
2549 The hexadecimal format is as follows:
2553 A 0x or 0X followed by a nonempty sequence of hexadecimal digits
2554 optionally containing a decimal-point character---normally @samp{.}, but
2555 it depends on the locale (@pxref{General Numeric}).
2558 An optional binary-exponent part, consisting of a character @samp{p} or
2559 @samp{P}, an optional sign, and a sequence of digits.
2564 Any remaining characters in the string. If @var{tailptr} is not a null
2565 pointer, a pointer to this tail of the string is stored in
2566 @code{*@var{tailptr}}.
2569 If the string is empty, contains only whitespace, or does not contain an
2570 initial substring that has the expected syntax for a floating-point
2571 number, no conversion is performed. In this case, @code{strtod} returns
2572 a value of zero and the value returned in @code{*@var{tailptr}} is the
2573 value of @var{string}.
2575 In a locale other than the standard @code{"C"} or @code{"POSIX"} locales,
2576 this function may recognize additional locale-dependent syntax.
2578 If the string has valid syntax for a floating-point number but the value
2579 is outside the range of a @code{double}, @code{strtod} will signal
2580 overflow or underflow as described in @ref{Math Error Reporting}.
2582 @code{strtod} recognizes four special input strings. The strings
2583 @code{"inf"} and @code{"infinity"} are converted to @math{@infinity{}},
2584 or to the largest representable value if the floating-point format
2585 doesn't support infinities. You can prepend a @code{"+"} or @code{"-"}
2586 to specify the sign. Case is ignored when scanning these strings.
2588 The strings @code{"nan"} and @code{"nan(@var{chars@dots{}})"} are converted
2589 to NaN. Again, case is ignored. If @var{chars@dots{}} are provided, they
2590 are used in some unspecified fashion to select a particular
2591 representation of NaN (there can be several).
2593 Since zero is a valid result as well as the value returned on error, you
2594 should check for errors in the same way as for @code{strtol}, by
2595 examining @var{errno} and @var{tailptr}.
2600 @deftypefun float strtof (const char *@var{string}, char **@var{tailptr})
2603 @deftypefunx {long double} strtold (const char *@var{string}, char **@var{tailptr})
2604 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2605 These functions are analogous to @code{strtod}, but return @code{float}
2606 and @code{long double} values respectively. They report errors in the
2607 same way as @code{strtod}. @code{strtof} can be substantially faster
2608 than @code{strtod}, but has less precision; conversely, @code{strtold}
2609 can be much slower but has more precision (on systems where @code{long
2610 double} is a separate type).
2612 These functions have been GNU extensions and are new to @w{ISO C99}.
2617 @deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr})
2620 @deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr})
2623 @deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})
2624 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2625 The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
2626 equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
2627 @code{strtold} functions but it handles wide character string.
2629 The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO
2630 C90}. The @code{wcstof} and @code{wcstold} functions were introduced in
2636 @deftypefun double atof (const char *@var{string})
2637 @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
2638 This function is similar to the @code{strtod} function, except that it
2639 need not detect overflow and underflow errors. The @code{atof} function
2640 is provided mostly for compatibility with existing code; using
2641 @code{strtod} is more robust.
2644 @Theglibc{} also provides @samp{_l} versions of these functions,
2645 which take an additional argument, the locale to use in conversion.
2647 See also @ref{Parsing of Integers}.
2649 @node System V Number Conversion
2650 @section Old-fashioned System V number-to-string functions
2652 The old @w{System V} C library provided three functions to convert
2653 numbers to strings, with unusual and hard-to-use semantics. @Theglibc{}
2654 also provides these functions and some natural extensions.
2656 These functions are only available in @theglibc{} and on systems descended
2657 from AT&T Unix. Therefore, unless these functions do precisely what you
2658 need, it is better to use @code{sprintf}, which is standard.
2660 All these functions are defined in @file{stdlib.h}.
2663 @comment SVID, Unix98
2664 @deftypefun {char *} ecvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2665 @safety{@prelim{}@mtunsafe{@mtasurace{:ecvt}}@asunsafe{}@acsafe{}}
2666 The function @code{ecvt} converts the floating-point number @var{value}
2667 to a string with at most @var{ndigit} decimal digits. The
2668 returned string contains no decimal point or sign. The first digit of
2669 the string is non-zero (unless @var{value} is actually zero) and the
2670 last digit is rounded to nearest. @code{*@var{decpt}} is set to the
2671 index in the string of the first digit after the decimal point.
2672 @code{*@var{neg}} is set to a nonzero value if @var{value} is negative,
2675 If @var{ndigit} decimal digits would exceed the precision of a
2676 @code{double} it is reduced to a system-specific value.
2678 The returned string is statically allocated and overwritten by each call
2681 If @var{value} is zero, it is implementation defined whether
2682 @code{*@var{decpt}} is @code{0} or @code{1}.
2684 For example: @code{ecvt (12.3, 5, &d, &n)} returns @code{"12300"}
2685 and sets @var{d} to @code{2} and @var{n} to @code{0}.
2689 @comment SVID, Unix98
2690 @deftypefun {char *} fcvt (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2691 @safety{@prelim{}@mtunsafe{@mtasurace{:fcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2692 The function @code{fcvt} is like @code{ecvt}, but @var{ndigit} specifies
2693 the number of digits after the decimal point. If @var{ndigit} is less
2694 than zero, @var{value} is rounded to the @math{@var{ndigit}+1}'th place to the
2695 left of the decimal point. For example, if @var{ndigit} is @code{-1},
2696 @var{value} will be rounded to the nearest 10. If @var{ndigit} is
2697 negative and larger than the number of digits to the left of the decimal
2698 point in @var{value}, @var{value} will be rounded to one significant digit.
2700 If @var{ndigit} decimal digits would exceed the precision of a
2701 @code{double} it is reduced to a system-specific value.
2703 The returned string is statically allocated and overwritten by each call
2708 @comment SVID, Unix98
2709 @deftypefun {char *} gcvt (double @var{value}, int @var{ndigit}, char *@var{buf})
2710 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2711 @c gcvt calls sprintf, that ultimately calls vfprintf, which malloc()s
2712 @c args_value if it's too large, but gcvt never exercises this path.
2713 @code{gcvt} is functionally equivalent to @samp{sprintf(buf, "%*g",
2714 ndigit, value}. It is provided only for compatibility's sake. It
2717 If @var{ndigit} decimal digits would exceed the precision of a
2718 @code{double} it is reduced to a system-specific value.
2721 As extensions, @theglibc{} provides versions of these three
2722 functions that take @code{long double} arguments.
2726 @deftypefun {char *} qecvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2727 @safety{@prelim{}@mtunsafe{@mtasurace{:qecvt}}@asunsafe{}@acsafe{}}
2728 This function is equivalent to @code{ecvt} except that it takes a
2729 @code{long double} for the first parameter and that @var{ndigit} is
2730 restricted by the precision of a @code{long double}.
2735 @deftypefun {char *} qfcvt (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg})
2736 @safety{@prelim{}@mtunsafe{@mtasurace{:qfcvt}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
2737 This function is equivalent to @code{fcvt} except that it
2738 takes a @code{long double} for the first parameter and that @var{ndigit} is
2739 restricted by the precision of a @code{long double}.
2744 @deftypefun {char *} qgcvt (long double @var{value}, int @var{ndigit}, char *@var{buf})
2745 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2746 This function is equivalent to @code{gcvt} except that it takes a
2747 @code{long double} for the first parameter and that @var{ndigit} is
2748 restricted by the precision of a @code{long double}.
2753 The @code{ecvt} and @code{fcvt} functions, and their @code{long double}
2754 equivalents, all return a string located in a static buffer which is
2755 overwritten by the next call to the function. @Theglibc{}
2756 provides another set of extended functions which write the converted
2757 string into a user-supplied buffer. These have the conventional
2760 @code{gcvt_r} is not necessary, because @code{gcvt} already uses a
2761 user-supplied buffer.
2765 @deftypefun int ecvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2766 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2767 The @code{ecvt_r} function is the same as @code{ecvt}, except
2768 that it places its result into the user-specified buffer pointed to by
2769 @var{buf}, with length @var{len}. The return value is @code{-1} in
2770 case of an error and zero otherwise.
2772 This function is a GNU extension.
2776 @comment SVID, Unix98
2777 @deftypefun int fcvt_r (double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2778 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2779 The @code{fcvt_r} function is the same as @code{fcvt}, except that it
2780 places its result into the user-specified buffer pointed to by
2781 @var{buf}, with length @var{len}. The return value is @code{-1} in
2782 case of an error and zero otherwise.
2784 This function is a GNU extension.
2789 @deftypefun int qecvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2790 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2791 The @code{qecvt_r} function is the same as @code{qecvt}, except
2792 that it places its result into the user-specified buffer pointed to by
2793 @var{buf}, with length @var{len}. The return value is @code{-1} in
2794 case of an error and zero otherwise.
2796 This function is a GNU extension.
2801 @deftypefun int qfcvt_r (long double @var{value}, int @var{ndigit}, int *@var{decpt}, int *@var{neg}, char *@var{buf}, size_t @var{len})
2802 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2803 The @code{qfcvt_r} function is the same as @code{qfcvt}, except
2804 that it places its result into the user-specified buffer pointed to by
2805 @var{buf}, with length @var{len}. The return value is @code{-1} in
2806 case of an error and zero otherwise.
2808 This function is a GNU extension.