aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1997-04-21 11:38:46 +0000
committerUlrich Drepper <drepper@redhat.com>1997-04-21 11:38:46 +0000
commitb4012b7542183a57cd92514e2359b8110609e52a (patch)
tree4fa35d6484e1f919c3649922545d740b9da14c08 /manual
parent406f977a5a0e61732fd13cdeec62c3f14bacc317 (diff)
downloadglibc-b4012b7542183a57cd92514e2359b8110609e52a.tar
glibc-b4012b7542183a57cd92514e2359b8110609e52a.tar.gz
glibc-b4012b7542183a57cd92514e2359b8110609e52a.tar.bz2
glibc-b4012b7542183a57cd92514e2359b8110609e52a.zip
Update.
1997-04-21 13:25 Ulrich Drepper <drepper@cygnus.com> * manual/arith.texi: Add description for INFINITY, _Imaginary_I, fpclassify & friends, and complex number operations. Update various other math functions for ISO C 9X. * manual/math.texi: Update various entries for ISO C 9X. Add description for complex number functions. Add description of rand48 function family. * manual/string.h: Add description of a64l and l64a. * math/cmathcalls.h: Fix typo. * stdlib/a64l.c: Pretty printing. * stdlib/seed48_r.c: Also reset `a' and `c' to default values. * stdlib/srand48_r.c: Likewise. * stdlib/stdlib.h: Pretty printing. * sysdeps/i386/fpu/__math.h: Fix typo. * sysdeps/libm-ieee754/s_nearbyintf.c: Correctly name function. * sysdeps/libm-ieee754/s_nearbyintl.c: Likewise. 1997-04-19 22:16 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * sysdeps/m68k/fpu/e_pow.c: Rewrite handling of integral exponent. 1997-04-18 19:34 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * sysdeps/m68k/fpu/__math.h: Define optimized versions of isgreater, isgreaterequal, isless, islessequal, islessgreater, and isunordered. 1997-04-20 01:28 Richard Henderson <rth@tamu.edu> * rellns-sh: Handle files in the same directory correctly. 1997-04-20 11:22 Ulrich Drepper <drepper@cygnus.com> * csu/initfini.c: Place ALIGN instruction at correct positions. Patch by Richard Henderson <richard@twiddle.rth.home>. 1997-04-19 17:12 Ulrich Drepper <drepper@cygnus.com> * Make-dist: Don't automatically ignore .c files if the .S or .s file is ignored. * csu/Makefile (distribute): Add defs.awk. 1997-04-19 15:39 Ulrich Drepper <drepper@cygnus.com> * sysdeps/stub/shmat.c: Update to XPG4.2 interface. * sysdeps/stub/shmdt.c: Likewise. Reported by Thomas Bushnell, n/BSG. 1997-04-19 13:22 Ulrich Drepper <drepper@cygnus.com> * manual/stdio.texi: Add description of printf_size and printf_size_info. Partly based on the documentation by Larry McVoy. 1997-04-19 02:21 Ulrich Drepper <drepper@cygnus.com> * stdio-common/printf_size.c (printf_size): Correct values for `units'. Report by Larry McVoy <lm@neteng.engr.sgi.com>. * stdio-common/tst-printfsz.c: New file. * stdio-common/Makefile (tests): Add tst-printfsz.c. (CFLAGS-tst-printfsz.c): Define to prevent warnings about format strings. 1997-04-18 15:48 Ulrich Drepper <drepper@cygnus.com> * login/utmp.h: Add prototype for updwtmp. * login/logwtmp.c: Add new function updwtmp which allows to write a complete record to the wtmp file. Patch by Miquel van Smoorenburg <miquels@cistron.nl>. 1997-04-17 17:57 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * math/Makefile (headers): Add mathbits.h. 1997-04-16 21:20 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * sysdeps/m68k/fpu/__math.h: Add inlined sincos{,l,f}. * sysdeps/m68k/fpu/s_sincos.c: New file. * sysdeps/m68k/fpu/s_sincosf.c: New file. * sysdeps/m68k/fpu/s_sincosl.c: New file. * sysdeps/libm-ieee754/e_scalb.c: Use internal names of the functions. * sysdeps/libm-ieee754/e_scalbl.c: Likewise. * sysdeps/libm-ieee754/s_ctanh.c: Use isfinite instead of finite. * sysdeps/libm-ieee754/s_ctanhf.c: Likewise. * sysdeps/libm-ieee754/s_ctanhl.c: Likewise. * sysdeps/libm-ieee754/s_ctan.c: Likewise. * sysdeps/libm-ieee754/s_ctanf.c: Likewise. * sysdeps/libm-ieee754/s_ctanl.c: Likewise. Fix type of `res'. 1997-04-18 11:21 Ulrich Drepper <drepper@cygnus.com> * shadow/fgetspent_r.c: Set *RESULT to NULL before returning error. Patch by Thorsten Kukuk <kukuk@vt.uni-paderborn.de>.
Diffstat (limited to 'manual')
-rw-r--r--manual/arith.texi404
-rw-r--r--manual/math.texi840
-rw-r--r--manual/string.texi81
3 files changed, 1251 insertions, 74 deletions
diff --git a/manual/arith.texi b/manual/arith.texi
index d8703ea6c1..86fb2667a0 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -3,12 +3,17 @@
This chapter contains information about functions for doing basic
arithmetic operations, such as splitting a float into its integer and
-fractional parts. These functions are declared in the header file
-@file{math.h}.
+fractional parts or retrieving the imaginary part of a complex value.
+These functions are declared in the header files @file{math.h} and
+@file{complex.h}.
@menu
+* Infinity:: What is Infinity and how to test for it.
* Not a Number:: Making NaNs and testing for NaNs.
+* Imaginary Unit:: Constructing complex Numbers.
* Predicates on Floats:: Testing for infinity and for NaNs.
+* Floating-Point Classes:: Classifiy floating-point numbers.
+* Operations on Complex:: Projections, Conjugates, and Decomposing.
* Absolute Value:: Absolute value functions.
* Normalization Functions:: Hacks for radix-2 representations.
* Rounding and Remainders:: Determining the integer and
@@ -19,6 +24,44 @@ fractional parts. These functions are declared in the header file
from strings.
@end menu
+@node Infinity
+@section Infinity Values
+@cindex Infinity
+@cindex IEEE floating point
+
+Mathematical operations easily can produce as the result values which
+are not representable by the floating-point format. The functions in
+the mathematics library also have this problem. The situation is
+generally solved by raising an overflow exception and by returning a
+huge value.
+
+The @w{IEEE 754} floating-point defines a special value to be used in
+these situations. There is a special value for infinity.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro float_t INFINITY
+A expression representing the inifite value. @code{INFINITY} values are
+produce by mathematical operations like @code{1.0 / 0.0}. It is
+possible to continue the computations with this value since the basic
+operations as well as the mathematical library functions are prepared to
+handle values like this.
+
+Beside @code{INFINITY} also the value @code{-INIFITY} is representable
+and it is handled differently if needed. It is possible to test a
+variables for infinite value using a simple comparison but the
+recommended way is to use the the @code{isinf} function.
+
+This macro was introduced in the @w{ISO C 9X} standard.
+@end deftypevr
+
+@vindex HUGE_VAL
+The macros @code{HUGE_VAL}, @code{HUGE_VALF} and @code{HUGE_VALL} are
+defined in a similar way but they are not required to represent the
+infinite value, only a very large value (@pxref{Domain and Range Errors}).
+If actually infinity is wanted, @code{INFINITY} should be used.
+
+
@node Not a Number
@section ``Not a Number'' Values
@cindex NaN
@@ -54,6 +97,46 @@ such as by defining @code{_GNU_SOURCE}, and then you must include
@file{math.h}.)
@end deftypevr
+@node Imaginary Unit
+@section Constructing complex Numbers
+
+@pindex complex.h
+To construct complex numbers it is necessary have a way to express the
+imaginary part of the numbers. In mathematics one uses the symbol ``i''
+to mark a number as imaginary. For convenienve the @file{complex.h}
+header defines two macros which allow to use a similar easy notation.
+
+@deftypevr Macro float_t _Imaginary_I
+This macro is a (compiler specific) representation of the value ``1i''.
+I.e., it is the value for which
+
+@smallexample
+_Imaginary_I * _Imaginary_I = -1
+@end smallexample
+
+@noindent
+One can use it to easily construct complex number like in
+
+@smallexample
+3.0 - _Imaginary_I * 4.0
+@end smallexample
+
+@noindent
+which results in the complex number with a real part of 3.0 and a
+imaginary part -4.0.
+@end deftypevr
+
+@noindent
+A more intuitive approach is to use the following macro.
+
+@deftypevr Macro float_t I
+This macro has exactly the same value as @code{_Imaginary_I}. The
+problem is that the name @code{I} very easily can clash with macros or
+variables in programs and so it might be a good idea to avoid this name
+and stay at the safe side by using @code{_Imaginary_I}.
+@end deftypevr
+
+
@node Predicates on Floats
@section Predicates on Floats
@@ -66,6 +149,10 @@ functions, and thus are available if you define @code{_BSD_SOURCE} or
@comment math.h
@comment BSD
@deftypefun int isinf (double @var{x})
+@end deftypefun
+@deftypefun int isinff (float @var{x})
+@end deftypefun
+@deftypefun int isinfl (long double @var{x})
This function returns @code{-1} if @var{x} represents negative infinity,
@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
@end deftypefun
@@ -73,6 +160,10 @@ This function returns @code{-1} if @var{x} represents negative infinity,
@comment math.h
@comment BSD
@deftypefun int isnan (double @var{x})
+@end deftypefun
+@deftypefun int isnanf (float @var{x})
+@end deftypefun
+@deftypefun int isnanl (long double @var{x})
This function returns a nonzero value if @var{x} is a ``not a number''
value, and zero otherwise. (You can just as well use @code{@var{x} !=
@var{x}} to get the same result).
@@ -81,6 +172,10 @@ value, and zero otherwise. (You can just as well use @code{@var{x} !=
@comment math.h
@comment BSD
@deftypefun int finite (double @var{x})
+@end deftypefun
+@deftypefun int finitef (float @var{x})
+@end deftypefun
+@deftypefun int finitel (long double @var{x})
This function returns a nonzero value if @var{x} is finite or a ``not a
number'' value, and zero otherwise.
@end deftypefun
@@ -103,6 +198,189 @@ does not fit the @w{ISO C} specification.
@strong{Portability Note:} The functions listed in this section are BSD
extensions.
+@node Floating-Point Classes
+@section Floating-Point Number Classification Functions
+
+Instead of using the BSD specific functions from the last section it is
+better to use those in this section will are introduced in the @w{ISO C
+9X} standard and are therefore widely available.
+
+@comment math.h
+@comment ISO
+@deftypefun int fpclassify (@emph{float-type} @var{x})
+This is a generic macro which works on all floating-point types and
+which returns a value of type @code{int}. The possible values are:
+
+@vtable @code
+@item FP_NAN
+ The floating-point number @var{x} is ``Not a Number'' (@pxref{Not a Number})
+@item FP_INFINITE
+ The value of @var{x} is either plus or minus infinity (@pxref{Infinity})
+@item FP_ZERO
+ The value of @var{x} is zero. In floating-point formats like @w{IEEE
+ 754} where the zero value can be signed this value is also returned if
+ @var{x} is minus zero.
+@item FP_SUBNORMAL
+ Some floating-point formats (such as @w{IEEE 754}) allow floating-point
+ numbers to be represented in a denormalized format. This happens if the
+ absolute value of the number is too small to be represented in the
+ normal format. @code{FP_SUBNORMAL} is returned for such values of @var{x}.
+@item FP_NORMAL
+ This value is returned for all other cases which means the number is a
+ plain floating-point number without special meaning.
+@end vtable
+
+This macro is useful if more than property of a number must be
+tested. If one only has to test for, e.g., a NaN value, there are
+function which are faster.
+@end deftypefun
+
+The remainder of this section introduces some more specific functions.
+They might be implemented faster than the call to @code{fpclassify} and
+if the actual need in the program is covered be these functions they
+should be used (and not @code{fpclassify}).
+
+@comment math.h
+@comment ISO
+@deftypefun int isfinite (@emph{float-type} @var{x})
+The value returned by this macro is nonzero if the value of @var{x} is
+not plus or minus infinity and not NaN. I.e., it could be implemented as
+
+@smallexample
+(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)
+@end smallexample
+
+@code{isfinite} is also implemented as a macro which can handle all
+floating-point types. Programs should use this function instead of
+@var{finite} (@pxref{Predicates on Floats}).
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int isnormal (@emph{float-type} @var{x})
+If @code{isnormal} returns a nonzero value the value or @var{x} is
+neither a NaN, infinity, zero, nor a denormalized number. I.e., it
+could be implemented as
+
+@smallexample
+(fpclassify (x) == FP_NORMAL)
+@end smallexample
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int isnan (@emph{float-type} @var{x})
+The situation with this macro is a bit complicated. Here @code{isnan}
+is a macro which can handle all kinds of floating-point types. It
+returns a nonzero value is @var{x} does not represent a NaN value and
+could be written like this
+
+@smallexample
+(fpclassify (x) == FP_NAN)
+@end smallexample
+
+The complication is that there is a function of the same name and the
+same semantic defined for compatibility with BSD (@pxref{Predicates on
+Floats}). Fortunately this should not yield to problems in most cases
+since the macro and the function have the same semantic. Should in a
+situation the function be absolutely necessary one can use
+
+@smallexample
+(isnan) (x)
+@end smallexample
+
+@noindent
+to avoid the macro expansion. Using the macro has two big adavantages:
+it is more portable and one does not have to choose the right function
+among @code{isnan}, @code{isnanf}, and @code{isnanl}.
+@end deftypefun
+
+
+@node Operations on Complex
+@section Projections, Conjugates, and Decomposing of Complex Numbers
+@cindex project complex numbers
+@cindex conjugate complex numbers
+@cindex decompose complex numbers
+
+This section lists functions performing some of the simple mathematical
+operations on complex numbers. Using any of the function requries that
+the C compiler understands the @code{complex} keyword, introduced to the
+C language in the @w{ISO C 9X} standard.
+
+@pindex complex.h
+The prototypes for all functions in this section can be found in
+@file{complex.h}. All functions are available in three variants, one
+for each of the three floating-point types.
+
+The easiest operation on complex numbers is the decomposition in the
+real part and the imaginary part. This is done by the next two
+functions.
+
+@comment complex.h
+@comment ISO
+@deftypefun double creal (complex double @var{z})
+@end deftypefun
+@deftypefun float crealf (complex float @var{z})
+@end deftypefun
+@deftypefun {long double} creall (complex long double @var{z})
+These functions return the real part of the complex number @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun double cimag (complex double @var{z})
+@end deftypefun
+@deftypefun float cimagf (complex float @var{z})
+@end deftypefun
+@deftypefun {long double} cimagl (complex long double @var{z})
+These functions return the imaginary part of the complex number @var{z}.
+@end deftypefun
+
+
+The conjugate complex value of a given complex number has the same value
+for the real part but the complex part is negated.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} conj (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} conjf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} conjl (complex long double @var{z})
+These functions return the conjugate complex value of the complex number
+@var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun double carg (complex double @var{z})
+@end deftypefun
+@deftypefun float cargf (complex float @var{z})
+@end deftypefun
+@deftypefun {long double} cargl (complex long double @var{z})
+These functions return argument of the complex number @var{z}.
+
+Mathematically, the argument is the phase angle of @var{z} with a branch
+cut along the negative real axis.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cproj (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} cprojf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} cprojl (complex long double @var{z})
+Return the projection of the complex value @var{z} on the Riemann
+sphere. Values with a infinite complex part (even if the real part
+is NaN) are projected to positive infinte on the real axis. If the real part is infinite, the result is equivalent to
+
+@smallexample
+INFINITY + I * copysign (0.0, cimag (z))
+@end smallexample
+@end deftypefun
+
+
@node Absolute Value
@section Absolute Value
@cindex absolute value functions
@@ -117,7 +395,8 @@ whose imaginary part is @var{y}, the absolute value is @w{@code{sqrt
@pindex math.h
@pindex stdlib.h
Prototypes for @code{abs} and @code{labs} are in @file{stdlib.h};
-@code{fabs} and @code{cabs} are declared in @file{math.h}.
+@code{fabs}, @code{fabsf} and @code{fabsl} are declared in @file{math.h};
+@code{cabs}, @code{cabsf} and @code{cabsl} are declared in @file{complex.h}.
@comment stdlib.h
@comment ISO
@@ -139,20 +418,28 @@ are of type @code{long int} rather than @code{int}.
@comment math.h
@comment ISO
@deftypefun double fabs (double @var{number})
+@end deftypefun
+@deftypefun float fabsf (float @var{number})
+@end deftypefun
+@deftypefun {long double} fabsl (long double @var{number})
This function returns the absolute value of the floating-point number
@var{number}.
@end deftypefun
-@comment math.h
-@comment BSD
-@deftypefun double cabs (struct @{ double real, imag; @} @var{z})
-The @code{cabs} function returns the absolute value of the complex
-number @var{z}, whose real part is @code{@var{z}.real} and whose
-imaginary part is @code{@var{z}.imag}. (See also the function
-@code{hypot} in @ref{Exponents and Logarithms}.) The value is:
+@comment complex.h
+@comment ISO
+@deftypefun double cabs (complex double @var{z})
+@end deftypefun
+@deftypefun float cabsf (complex float @var{z})
+@end deftypefun
+@deftypefun {long double} cabsl (complex long double @var{z})
+These functions return the absolute value of the complex number @var{z}.
+The compiler must support complex numbers to use these functions. (See
+also the function @code{hypot} in @ref{Exponents and Logarithms}.) The
+value is:
@smallexample
-sqrt (@var{z}.real*@var{z}.real + @var{z}.imag*@var{z}.imag)
+sqrt (creal (@var{z}) * creal (@var{z}) + cimag (@var{z}) * cimag (@var{z}))
@end smallexample
@end deftypefun
@@ -174,7 +461,11 @@ All these functions are declared in @file{math.h}.
@comment math.h
@comment ISO
@deftypefun double frexp (double @var{value}, int *@var{exponent})
-The @code{frexp} function is used to split the number @var{value}
+@end deftypefun
+@deftypefun float frexpf (float @var{value}, int *@var{exponent})
+@end deftypefun
+@deftypefun {long double} frexpl (long double @var{value}, int *@var{exponent})
+These functions are used to split the number @var{value}
into a normalized fraction and an exponent.
If the argument @var{value} is not zero, the return value is @var{value}
@@ -193,7 +484,11 @@ zero is stored in @code{*@var{exponent}}.
@comment math.h
@comment ISO
@deftypefun double ldexp (double @var{value}, int @var{exponent})
-This function returns the result of multiplying the floating-point
+@end deftypefun
+@deftypefun float ldexpf (float @var{value}, int @var{exponent})
+@end deftypefun
+@deftypefun {long double} ldexpl (long double @var{value}, int @var{exponent})
+These functions return the result of multiplying the floating-point
number @var{value} by 2 raised to the power @var{exponent}. (It can
be used to reassemble floating-point numbers that were taken apart
by @code{frexp}.)
@@ -207,13 +502,21 @@ equivalent to those of @code{ldexp} and @code{frexp}:
@comment math.h
@comment BSD
@deftypefun double scalb (double @var{value}, int @var{exponent})
+@end deftypefun
+@deftypefun float scalbf (float @var{value}, int @var{exponent})
+@end deftypefun
+@deftypefun {long double} scalbl (long double @var{value}, int @var{exponent})
The @code{scalb} function is the BSD name for @code{ldexp}.
@end deftypefun
@comment math.h
@comment BSD
@deftypefun double logb (double @var{x})
-This BSD function returns the integer part of the base-2 logarithm of
+@end deftypefun
+@deftypefun float logbf (float @var{x})
+@end deftypefun
+@deftypefun {long double} logbl (long double @var{x})
+These BSD functions return the integer part of the base-2 logarithm of
@var{x}, an integer value represented in type @code{double}. This is
the highest integer power of @code{2} contained in @var{x}. The sign of
@var{x} is ignored. For example, @code{logb (3.5)} is @code{1.0} and
@@ -231,11 +534,28 @@ The value returned by @code{logb} is one less than the value that
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double copysign (double @var{value}, double @var{sign})
-The @code{copysign} function returns a value whose absolute value is the
+@end deftypefun
+@deftypefun float copysignf (float @var{value}, float @var{sign})
+@end deftypefun
+@deftypefun {long double} copysignl (long double @var{value}, long double @var{sign})
+These functions return a value whose absolute value is the
same as that of @var{value}, and whose sign matches that of @var{sign}.
-This is a BSD function.
+This function appears in BSD and was standardized in @w{ISO C 9X}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int signbit (@emph{float-type} @var{x})
+@code{signbit} is a generic macro which can work on all floating-point
+types. It returns a nonzero value if the value of @var{x} has its sign
+bit set.
+
+This is not the same as @code{x < 0.0} since in some floating-point
+formats (e.g., @w{IEEE 754}) the zero value is optionally signed. The
+comparison @code{-0.0 < 0.0} will not be true while @code{signbit
+(-0.0)} will return a nonzeri value.
@end deftypefun
@node Rounding and Remainders
@@ -260,7 +580,11 @@ result as a @code{double} instead to get around this problem.
@comment math.h
@comment ISO
@deftypefun double ceil (double @var{x})
-The @code{ceil} function rounds @var{x} upwards to the nearest integer,
+@end deftypefun
+@deftypefun float ceilf (float @var{x})
+@end deftypefun
+@deftypefun {long double} ceill (long double @var{x})
+These functions round @var{x} upwards to the nearest integer,
returning that value as a @code{double}. Thus, @code{ceil (1.5)}
is @code{2.0}.
@end deftypefun
@@ -268,15 +592,23 @@ is @code{2.0}.
@comment math.h
@comment ISO
@deftypefun double floor (double @var{x})
-The @code{ceil} function rounds @var{x} downwards to the nearest
+@end deftypefun
+@deftypefun float floorf (float @var{x})
+@end deftypefun
+@deftypefun {long double} floorl (long double @var{x})
+These functions round @var{x} downwards to the nearest
integer, returning that value as a @code{double}. Thus, @code{floor
(1.5)} is @code{1.0} and @code{floor (-1.5)} is @code{-2.0}.
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double rint (double @var{x})
-This function rounds @var{x} to an integer value according to the
+@end deftypefun
+@deftypefun float rintf (float @var{x})
+@end deftypefun
+@deftypefun {long double} rintl (long double @var{x})
+These functions round @var{x} to an integer value according to the
current rounding mode. @xref{Floating Point Parameters}, for
information about the various rounding modes. The default
rounding mode is to round to the nearest integer; some machines
@@ -286,8 +618,24 @@ you explicit select another.
@comment math.h
@comment ISO
+@deftypefun double nearbyint (double @var{x})
+@end deftypefun
+@deftypefun float nearbyintf (float @var{x})
+@end deftypefun
+@deftypefun {long double} nearbyintl (long double @var{x})
+These functions return the same value as the @code{rint} functions but
+even some rounding actually takes place @code{nearbyint} does @emph{not}
+raise the inexact exception.
+@end deftypefun
+
+@comment math.h
+@comment ISO
@deftypefun double modf (double @var{value}, double *@var{integer-part})
-This function breaks the argument @var{value} into an integer part and a
+@end deftypefun
+@deftypefun float modff (flaot @var{value}, float *@var{integer-part})
+@end deftypefun
+@deftypefun {long double} modfl (long double @var{value}, long double *@var{integer-part})
+These functions break the argument @var{value} into an integer part and a
fractional part (between @code{-1} and @code{1}, exclusive). Their sum
equals @var{value}. Each of the parts has the same sign as @var{value},
so the rounding of the integer part is towards zero.
@@ -300,7 +648,11 @@ returns @code{0.5} and stores @code{2.0} into @code{intpart}.
@comment math.h
@comment ISO
@deftypefun double fmod (double @var{numerator}, double @var{denominator})
-This function computes the remainder from the division of
+@end deftypefun
+@deftypefun float fmodf (float @var{numerator}, float @var{denominator})
+@end deftypefun
+@deftypefun {long double} fmodl (long double @var{numerator}, long double @var{denominator})
+These functions compute the remainder from the division of
@var{numerator} by @var{denominator}. Specifically, the return value is
@code{@var{numerator} - @w{@var{n} * @var{denominator}}}, where @var{n}
is the quotient of @var{numerator} divided by @var{denominator}, rounded
@@ -317,7 +669,11 @@ If @var{denominator} is zero, @code{fmod} fails and sets @code{errno} to
@comment math.h
@comment BSD
@deftypefun double drem (double @var{numerator}, double @var{denominator})
-The function @code{drem} is like @code{fmod} except that it rounds the
+@end deftypefun
+@deftypefun float dremf (float @var{numerator}, float @var{denominator})
+@end deftypefun
+@deftypefun {long double} dreml (long double @var{numerator}, long double @var{denominator})
+These functions are like @code{fmod} etc except that it rounds the
internal quotient @var{n} to the nearest integer instead of towards zero
to an integer. For example, @code{drem (6.5, 2.3)} returns @code{-0.4},
which is @code{6.5} minus @code{6.9}.
diff --git a/manual/math.texi b/manual/math.texi
index 543647297f..78d567b367 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -7,14 +7,22 @@ these functions have prototypes declared in the header file
@file{math.h}.
@pindex math.h
-All of the functions that operate on floating-point numbers accept
-arguments and return results of type @code{double}. In the future,
-there may be additional functions that operate on @code{float} and
-@code{long double} values. For example, @code{cosf} and @code{cosl}
-would be versions of the @code{cos} function that operate on
-@code{float} and @code{long double} arguments, respectively. In the
-meantime, you should avoid using these names yourself. @xref{Reserved
-Names}.
+For all functions which take a single floating-point argument and for
+several other functions as well there are three different functions
+available for the type @code{double}, @code{float}, and @code{long
+double}. The @code{double} versions of the functions are mostly defined
+even in the @w{ISO C 89} standard. The @code{float} and @code{long
+double} variants are introduced in the numeric extensions for the C
+language which are part of the @w{ISO C 9X} standard.
+
+Which of the three versions of the function should be used depends on
+the situation. For most functions and implementation it is true that
+speed and precision do not go together. I.e., the @code{float} versions
+are normally faster than the @code{double} and @code{long double}
+versions. On the other hand the @code{long double} version has the
+highest precision. One should always think about the actual needs and
+in case of double using @code{double} is a good compromise.
+
@menu
* Domain and Range Errors:: Detecting overflow conditions and the like.
@@ -119,11 +127,15 @@ The arguments to all of these functions are in units of radians; recall
that pi radians equals 180 degrees.
@cindex pi (trigonometric constant)
-The math library doesn't define a symbolic constant for pi, but you can
-define your own if you need one:
+The math library does define a symbolic constant for pi in @file{math.h}
+when BSD compliance is required (@pxref{Feature Test Macros}). Beside
+pi several other constants are defined.
+
+@noindent
+In case it is not possible to use this macro one easily can define it:
@smallexample
-#define PI 3.14159265358979323846264338327
+#define M_PI 3.14159265358979323846264338327
@end smallexample
@noindent
@@ -134,21 +146,33 @@ You can also compute the value of pi with the expression @code{acos
@comment math.h
@comment ISO
@deftypefun double sin (double @var{x})
-This function returns the sine of @var{x}, where @var{x} is given in
+@end deftypefun
+@deftypefun float sinf (float @var{x})
+@end deftypefun
+@deftypefun {long double} sinl (long double @var{x})
+These functions return the sine of @var{x}, where @var{x} is given in
radians. The return value is in the range @code{-1} to @code{1}.
@end deftypefun
@comment math.h
@comment ISO
@deftypefun double cos (double @var{x})
-This function returns the cosine of @var{x}, where @var{x} is given in
+@end deftypefun
+@deftypefun float cosf (float @var{x})
+@end deftypefun
+@deftypefun {long double} cosl (long double @var{x})
+These functions return the cosine of @var{x}, where @var{x} is given in
radians. The return value is in the range @code{-1} to @code{1}.
@end deftypefun
@comment math.h
@comment ISO
@deftypefun double tan (double @var{x})
-This function returns the tangent of @var{x}, where @var{x} is given in
+@end deftypefun
+@deftypefun float tanf (float @var{x})
+@end deftypefun
+@deftypefun {long double} tanl (long double @var{x})
+These functions return the tangent of @var{x}, where @var{x} is given in
radians.
The following @code{errno} error conditions are defined for this function:
@@ -162,6 +186,76 @@ either positive or negative @code{HUGE_VAL}.
@end table
@end deftypefun
+In many applications where @code{sin} and @code{cos} are used, the value
+for the same argument of both of these functions is used at the same
+time. Since the algorithm to compute these values is very similar for
+both functions there is an additional function with computes both values
+at the same time.
+
+@comment math.h
+@comment GNU
+@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
+@end deftypefun
+@deftypefun void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
+@end deftypefun
+@deftypefun void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
+These functions return the sine of @var{x} in @code{*@var{sinx}} and the
+cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
+radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
+the range of @code{-1} to @code{1}.
+@end deftypefun
+
+@cindex complex trigonometric functions
+
+The trigonometric functions are in mathematics not only on real numbers.
+They can be extended to complex numbers and the @w{ISO C 9X} standard
+introduces these variants in the standard math library.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csin (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} csinf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} csinl (complex long double @var{z})
+These functions return the complex sine of the complex value in @var{z}.
+The mathematical definition of the complex sine is
+
+@smallexample
+sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))
+@end smallexample
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccos (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} ccosf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} ccosl (complex long double @var{z})
+These functions return the complex cosine of the complex value in @var{z}.
+The mathematical definition of the complex cosine is
+
+@smallexample
+cos (z) = 1/2 * (exp (z*i) + exp (-z*i))
+@end smallexample
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ctan (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} ctanf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} ctanl (complex long double @var{z})
+These functions return the complex tangent of the complex value in @var{z}.
+The mathematical definition of the complex tangent is
+
+@smallexample
+tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))
+@end smallexample
+@end deftypefun
+
@node Inverse Trig Functions
@section Inverse Trigonometric Functions
@@ -174,7 +268,11 @@ respectively.
@comment math.h
@comment ISO
@deftypefun double asin (double @var{x})
-This function computes the arc sine of @var{x}---that is, the value whose
+@end deftypefun
+@deftypefun float asinf (float @var{x})
+@end deftypefun
+@deftypefun {long double} asinl (long double @var{x})
+These functions compute the arc sine of @var{x}---that is, the value whose
sine is @var{x}. The value is in units of radians. Mathematically,
there are infinitely many such values; the one actually returned is the
one between @code{-pi/2} and @code{pi/2} (inclusive).
@@ -187,7 +285,11 @@ over the domain @code{-1} to @code{1}.
@comment math.h
@comment ISO
@deftypefun double acos (double @var{x})
-This function computes the arc cosine of @var{x}---that is, the value
+@end deftypefun
+@deftypefun float acosf (float @var{x})
+@end deftypefun
+@deftypefun {long double} acosl (long double @var{x})
+These functions compute the arc cosine of @var{x}---that is, the value
whose cosine is @var{x}. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between @code{0} and @code{pi} (inclusive).
@@ -201,7 +303,11 @@ over the domain @code{-1} to @code{1}.
@comment math.h
@comment ISO
@deftypefun double atan (double @var{x})
-This function computes the arc tangent of @var{x}---that is, the value
+@end deftypefun
+@deftypefun float atanf (float @var{x})
+@end deftypefun
+@deftypefun {long double} atanl (long double @var{x})
+These functions compute the arc tangent of @var{x}---that is, the value
whose tangent is @var{x}. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between @code{-pi/2} and @code{pi/2}
@@ -211,6 +317,10 @@ returned is the one between @code{-pi/2} and @code{pi/2}
@comment math.h
@comment ISO
@deftypefun double atan2 (double @var{y}, double @var{x})
+@end deftypefun
+@deftypefun float atan2f (float @var{y}, float @var{x})
+@end deftypefun
+@deftypefun {long double} atan2l (long double @var{y}, long double @var{x})
This is the two argument arc tangent function. It is similar to computing
the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
are used to determine the quadrant of the result, and @var{x} is
@@ -229,6 +339,51 @@ The function @code{atan2} sets @code{errno} to @code{EDOM} if both
case.
@end deftypefun
+@cindex inverse complex trigonometric functions
+
+The inverse trigonometric functions also exist is separate versions
+which are usable with complex numbers.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casin (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} casinf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} casinl (complex long double @var{z})
+These functions compute the complex arc sine of @var{z}---that is, the
+value whose sine is @var{z}. The value is in units of radians.
+
+Unlike the real version of the arc sine function @code{casin} has no
+limitation on the argument @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacos (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} cacosf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} cacosl (complex long double @var{z})
+These functions compute the complex arc cosine of @var{z}---that is, the
+value whose cosine is @var{z}. The value is in units of radians.
+
+Unlike the real version of the arc cosine function @code{cacos} has no
+limitation on the argument @var{z}.
+@end deftypefun
+
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catan (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} catanf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} catanl (complex long double @var{z})
+These functions compute the complex arc tangent of @var{z}---that is,
+the value whose tangent is @var{z}. The value is in units of radians.
+@end deftypefun
+
@node Exponents and Logarithms
@section Exponentiation and Logarithms
@@ -239,7 +394,11 @@ case.
@comment math.h
@comment ISO
@deftypefun double exp (double @var{x})
-The @code{exp} function returns the value of e (the base of natural
+@end deftypefun
+@deftypefun float expf (float @var{x})
+@end deftypefun
+@deftypefun {long double} expl (long double @var{x})
+These functions return the value of @code{e} (the base of natural
logarithms) raised to power @var{x}.
The function fails, and sets @code{errno} to @code{ERANGE}, if the
@@ -248,8 +407,41 @@ magnitude of the result is too large to be representable.
@comment math.h
@comment ISO
+@deftypefun double exp10 (double @var{x})
+@end deftypefun
+@deftypefun float exp10f (float @var{x})
+@end deftypefun
+@deftypefun {long double} exp10l (long double @var{x})
+These functions return the value of @code{10} raised to the power @var{x}.
+Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
+
+The function fails, and sets @code{errno} to @code{ERANGE}, if the
+magnitude of the result is too large to be representable.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double exp2 (double @var{x})
+@end deftypefun
+@deftypefun float exp2f (float @var{x})
+@end deftypefun
+@deftypefun {long double} exp2l (long double @var{x})
+These functions return the value of @code{2} raised to the power @var{x}.
+Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
+
+The function fails, and sets @code{errno} to @code{ERANGE}, if the
+magnitude of the result is too large to be representable.
+@end deftypefun
+
+
+@comment math.h
+@comment ISO
@deftypefun double log (double @var{x})
-This function returns the natural logarithm of @var{x}. @code{exp (log
+@end deftypefun
+@deftypefun float logf (floatdouble @var{x})
+@end deftypefun
+@deftypefun {long double} logl (long double @var{x})
+These functions return the natural logarithm of @var{x}. @code{exp (log
(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
C.
@@ -268,15 +460,35 @@ The argument is zero. The log of zero is not defined.
@comment math.h
@comment ISO
@deftypefun double log10 (double @var{x})
-This function returns the base-10 logarithm of @var{x}. Except for the
+@end deftypefun
+@deftypefun float log10f (float @var{x})
+@end deftypefun
+@deftypefun {long double} log10l (long double @var{x})
+These functions return the base-10 logarithm of @var{x}. Except for the
different base, it is similar to the @code{log} function. In fact,
@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
@end deftypefun
@comment math.h
@comment ISO
+@deftypefun double log2 (double @var{x})
+@end deftypefun
+@deftypefun float log2f (float @var{x})
+@end deftypefun
+@deftypefun {long double} log2l (long double @var{x})
+These functions return the base-2 logarithm of @var{x}. Except for the
+different base, it is similar to the @code{log} function. In fact,
+@code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
@deftypefun double pow (double @var{base}, double @var{power})
-This is a general exponentiation function, returning @var{base} raised
+@end deftypefun
+@deftypefun float powf (float @var{base}, float @var{power})
+@end deftypefun
+@deftypefun {long double} powl (long double @var{base}, long double @var{power})
+These are general exponentiation functions, returning @var{base} raised
to @var{power}.
@need 250
@@ -296,48 +508,142 @@ An underflow or overflow condition was detected in the result.
@comment math.h
@comment ISO
@deftypefun double sqrt (double @var{x})
-This function returns the nonnegative square root of @var{x}.
+@end deftypefun
+@deftypefun float sqrtf (float @var{x})
+@end deftypefun
+@deftypefun {long double} sqrtl (long double @var{x})
+These functions return the nonnegative square root of @var{x}.
The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
@var{x} is negative. Mathematically, the square root would be a complex
number.
+@c (@pxref{csqrt})
@end deftypefun
@cindex cube root function
@comment math.h
@comment BSD
@deftypefun double cbrt (double @var{x})
-This function returns the cube root of @var{x}. This function cannot
+@end deftypefun
+@deftypefun float cbrtf (float @var{x})
+@end deftypefun
+@deftypefun {long double} cbrtl (long double @var{x})
+These functions return the cube root of @var{x}. They cannot
fail; every representable real value has a representable real cube root.
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double hypot (double @var{x}, double @var{y})
-The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
+@end deftypefun
+@deftypefun float hypotf (float @var{x}, float @var{y})
+@end deftypefun
+@deftypefun {long double} hypotl (long double @var{x}, long double @var{y})
+These functions return @code{sqrt (@var{x}*@var{x} +
@var{y}*@var{y})}. (This is the length of the hypotenuse of a right
triangle with sides of length @var{x} and @var{y}, or the distance
-of the point (@var{x}, @var{y}) from the origin.) See also the function
-@code{cabs} in @ref{Absolute Value}.
+of the point (@var{x}, @var{y}) from the origin.) Using this function
+instead of the direct formula is highly appreciated since the error is
+much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double expm1 (double @var{x})
-This function returns a value equivalent to @code{exp (@var{x}) - 1}.
+@end deftypefun
+@deftypefun float expm1f (float @var{x})
+@end deftypefun
+@deftypefun {long double} expm1l (long double @var{x})
+These functions return a value equivalent to @code{exp (@var{x}) - 1}.
It is computed in a way that is accurate even if the value of @var{x} is
near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
to subtraction of two numbers that are nearly equal.
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double log1p (double @var{x})
+@end deftypefun
+@deftypefun float log1pf (float @var{x})
+@end deftypefun
+@deftypefun {long double} log1pl (long double @var{x})
This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
It is computed in a way that is accurate even if the value of @var{x} is
near zero.
@end deftypefun
+@cindex complex exponentiation functions
+@cindex complex logarithm functions
+
+@w{ISO C 9X} defines variants of some of the exponentiation and
+logarithm functions. As for the other functions handlung complex
+numbers these functions are perhaps better optimized and provide better
+error checking than a direct use of the formulas of the mathematical
+definition.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cexp (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} cexpf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} cexpl (complex long double @var{z})
+These functions return the value of @code{e} (the base of natural
+logarithms) raised to power of the complex value @var{z}.
+
+Mathematically this corresponds to the value
+
+@smallexample
+exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))
+@end smallexample
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} clog (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} clogf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} clogl (complex long double @var{z})
+These functions return the natural logarithm of the complex value
+@var{z}. Unlike the real value version @code{log} and its variants,
+@code{clog} has no limit for the range of its argument @var{z}.
+
+Mathematically this corresponds to the value
+
+@smallexample
+log (z) = log (cabs (z)) + I * carg (z)
+@end smallexample
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csqrt (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} csqrtf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} csqrtl (complex long double @var{z})
+These functions return the complex root of the argument @var{z}. Unlike
+the @code{sqrt} function these functions do not have any restriction on
+the value of the argument.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
+@end deftypefun
+@deftypefun {complex float} cpowf (complex float @var{base}, complex float @var{power})
+@end deftypefun
+@deftypefun {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
+These functions return the complex value @var{BASE} raised to the power of
+@var{power}. This is computed as
+
+@smallexample
+cpow (x, y) = cexp (y * clog (x))
+@end smallexample
+@end deftypefun
+
+
@node Hyperbolic Functions
@section Hyperbolic Functions
@cindex hyperbolic functions
@@ -348,8 +654,12 @@ see @ref{Exponents and Logarithms}.
@comment math.h
@comment ISO
@deftypefun double sinh (double @var{x})
-The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
-mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}. The
+@end deftypefun
+@deftypefun float sinhf (float @var{x})
+@end deftypefun
+@deftypefun {long double} sinhl (long double @var{x})
+These functions return the hyperbolic sine of @var{x}, defined
+mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. The
function fails, and sets @code{errno} to @code{ERANGE}, if the value of
@var{x} is too large; that is, if overflow occurs.
@end deftypefun
@@ -357,8 +667,12 @@ function fails, and sets @code{errno} to @code{ERANGE}, if the value of
@comment math.h
@comment ISO
@deftypefun double cosh (double @var{x})
-The @code{cosh} function returns the hyperbolic cosine of @var{x},
-defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
+@end deftypefun
+@deftypefun float coshf (float @var{x})
+@end deftypefun
+@deftypefun {long double} coshl (long double @var{x})
+These function return the hyperbolic cosine of @var{x},
+defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
The function fails, and sets @code{errno} to @code{ERANGE}, if the value
of @var{x} is too large; that is, if overflow occurs.
@end deftypefun
@@ -366,36 +680,136 @@ of @var{x} is too large; that is, if overflow occurs.
@comment math.h
@comment ISO
@deftypefun double tanh (double @var{x})
-This function returns the hyperbolic tangent of @var{x}, whose
+@end deftypefun
+@deftypefun float tanhf (float @var{x})
+@end deftypefun
+@deftypefun {long double} tanhl (long double @var{x})
+These functions return the hyperbolic tangent of @var{x}, whose
mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
@end deftypefun
+@cindex hyperbolic functions
+
+There are counterparts for these hyperbolic functions which work with
+complex valued arguments. They should always be used instead of the
+obvious mathematical formula since the implementations in the math
+library are optimized for accuracy and speed.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csinh (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} csinhf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} csinhl (complex long double @var{z})
+These functions return the complex hyperbolic sine of @var{z}, defined
+mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}. The
+function fails, and sets @code{errno} to @code{ERANGE}, if the value of
+result is too large.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccosh (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} ccoshf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} ccoshl (complex long double @var{z})
+These functions return the complex hyperbolic cosine of @var{z}, defined
+mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}. The
+function fails, and sets @code{errno} to @code{ERANGE}, if the value of
+result is too large.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ctanh (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} ctanhf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} ctanhl (complex long double @var{z})
+These functions return the complex hyperbolic tangent of @var{z}, whose
+mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
+@end deftypefun
+
+
@cindex inverse hyperbolic functions
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double asinh (double @var{x})
-This function returns the inverse hyperbolic sine of @var{x}---the
+@end deftypefun
+@deftypefun float asinhf (float @var{x})
+@end deftypefun
+@deftypefun {long double} asinhl (long double @var{x})
+These functions return the inverse hyperbolic sine of @var{x}---the
value whose hyperbolic sine is @var{x}.
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double acosh (double @var{x})
-This function returns the inverse hyperbolic cosine of @var{x}---the
+@end deftypefun
+@deftypefun float acoshf (float @var{x})
+@end deftypefun
+@deftypefun {long double} acoshl (long double @var{x})
+These functions return the inverse hyperbolic cosine of @var{x}---the
value whose hyperbolic cosine is @var{x}. If @var{x} is less than
@code{1}, @code{acosh} returns @code{HUGE_VAL}.
@end deftypefun
@comment math.h
-@comment BSD
+@comment ISO
@deftypefun double atanh (double @var{x})
-This function returns the inverse hyperbolic tangent of @var{x}---the
+@end deftypefun
+@deftypefun float atanhf (float @var{x})
+@end deftypefun
+@deftypefun {long double} atanhl (long double @var{x})
+These functions return the inverse hyperbolic tangent of @var{x}---the
value whose hyperbolic tangent is @var{x}. If the absolute value of
@var{x} is greater than or equal to @code{1}, @code{atanh} returns
@code{HUGE_VAL}.
@end deftypefun
+@cindex inverse complex hyperbolic functions
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casinh (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} casinhf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} casinhl (complex long double @var{z})
+These functions return the inverse complex hyperbolic sine of
+@var{z}---the value whose complex hyperbolic sine is @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacosh (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} cacoshf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} cacoshl (complex long double @var{z})
+These functions return the inverse complex hyperbolic cosine of
+@var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike
+the real valued function @code{acosh} there is not limit for the range
+of the argument.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catanh (complex double @var{z})
+@end deftypefun
+@deftypefun {complex float} catanhf (complex float @var{z})
+@end deftypefun
+@deftypefun {complex long double} catanhl (complex long double @var{z})
+These functions return the inverse complex hyperbolic tangent of
+@var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike
+the real valued function @code{atanh} there is not limit for the range
+of the argument.
+@end deftypefun
+
@node Pseudo-Random Numbers
@section Pseudo-Random Numbers
@cindex random numbers
@@ -431,6 +845,7 @@ ones, @code{rand} and @code{srand}.
@menu
* ISO Random:: @code{rand} and friends.
* BSD Random:: @code{random} and friends.
+* SVID Random:: @code{drand48} and friends.
@end menu
@node ISO Random
@@ -526,3 +941,346 @@ The return value is the previous value of the state information array.
You can use thise value later as an argument to @code{setstate} to
restore that state.
@end deftypefun
+
+
+@node SVID Random
+@subsection SVID Random Number Function
+
+The C library on SVID systems contains yet another kind of random number
+generator functions. They use a state of 48 bits of data. The user can
+choose among a collection of functions which all return the random bits
+in different forms.
+
+Generally there are two kinds of functions: those which use a state of
+the random number generator which is shared among several functions and
+by all threads of the process. The second group of functions require
+the user to handle the state.
+
+All functions have in common that they use the same congruential
+formula with the same constants. The formula is
+
+@smallexample
+Y = (a * X + c) mod m
+@end smallexample
+
+@noindent
+where @var{X} is the state of the generator at the beginning and
+@var{Y} the state at the end. @code{a} and @code{c} are constants
+determining the way the generator work. By default they are
+
+@smallexample
+a = 0x5DEECE66D = 25214903917
+c = 0xb = 11
+@end smallexample
+
+@noindent
+but they can also be changed by the user. @code{m} is of course 2^48
+since the state consists of a 48 bit array.
+
+
+@comment stdlib.h
+@comment SVID
+@deftypefun double drand48 ()
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive). The random bits are determined by the global
+state of the random number generator in the C library.
+
+Since the @code{double} type according to @w{IEEE 754} has a 52 bit
+mantissa this means 4 bits are not initialized by the random number
+generator. These are (of course) chosen to be the least significant
+bits and they are initialized to @code{0}.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun double erand48 (unsigned short int @var{xsubi}[3])
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive), similar to @code{drand48}. The argument is
+an array describing the state of the random number generator.
+
+This function can be called subsequently since it updates the array to
+guarantee random numbers. The array should have been initialized before
+using to get reproducible results.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} lrand48 ()
+The @code{lrand48} functions return an integer value in the range of
+@code{0} to @code{2^31} (exclusive). Even if the size of the @code{long
+int} type can take more than 32 bits no higher numbers are returned.
+The random bits are determined by the global state of the random number
+generator in the C library.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
+This function is similar to the @code{lrand48} function in that it
+returns a number in the range of @code{0} to @code{2^31} (exclusive) but
+the state of the random number generator used to produce the random bits
+is determined by the array provided as the parameter to the function.
+
+The numbers in the array are afterwards updated so that subsequent calls
+to this function yield to different results (as it is expected by a
+random number generator). The array should have been initialized before
+the first call to get reproducible results.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} mrand48 ()
+The @code{mrand48} function is similar to @code{lrand48}. The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
+The @code{jrand48} function is similar to @code{nrand48}. The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive). For the @code{xsubi} parameter the same
+requirements are necessary.
+@end deftypefun
+
+The internal state of the random number generator can be initialized in
+several ways. The functions differ in the completeness of the
+information provided.
+
+@comment stdlib.h
+@comment SVID
+@deftypefun void srand48 (long int @var{seedval}))
+The @code{srand48} function sets the most significant 32 bits of the
+state internal state of the random number generator to the least
+significant 32 bits of the @var{seedval} parameter. The lower 16 bts
+are initilialized to the value @code{0x330E}. Even if the @code{long
+int} type contains more the 32 bits only the lower 32 bits are used.
+
+Due to this limitation the initialization of the state using this
+function of not very useful. But it makes it easy to use a constrcut
+like @code{srand48 (time (0))}.
+
+A side-effect of this function is that the values @code{a} and @code{c}
+from the internal state, which are used in the congruential formula,
+are reset to the default values given above. This is of importance once
+the user called the @code{lcong48} function (see below).
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID
+@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
+The @code{seed48} function initializes all 48 bits of the state of the
+internal random number generator from the content of the parameter
+@var{seed16v}. Here the lower 16 bits of the first element of
+@var{see16v} initialize the least significant 16 bits of the internal
+state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
+16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
+initialize the most significant 16 bits of the state.
+
+Unlike @code{srand48} this function lets the user initialize all 48 bits
+of the state.
+
+The value returned by @code{seed48} is a pointer to an array containing
+the values of the internal state before the change. This might be
+useful to restart the random number generator at a certain state.
+Otherwise, the value can simply be ignored.
+
+As for @code{srand48}, the values @code{a} and @code{c} from the
+congruential formula are reset to the default values.
+@end deftypefun
+
+There is one more function to initialize the random number generator
+which allows to specify even more information by allowing to change the
+parameters in the congruential formula.
+
+@comment stdlib.h
+@comment SVID
+@deftypefun void lcong48 (unsigned short int @var{param}[7])
+The @code{lcong48} function allows the user to change the complete state
+of the random number generator. Unlike @code{srand48} and
+@code{seed48}, this function also changes the constants in the
+congruential formula.
+
+From the seven elements in the array @var{param} the least significant
+16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
+determine the the initial state, the least 16 bits of
+@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
+constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
+@code{c}.
+@end deftypefun
+
+All the above functions have in common that they use the global
+parameters for the congruential formula. In multi-threaded programs it
+might sometimes be useful to have different parameters in different
+threads. For this reason all the above functions have a counterpart
+which works on a description of the random number generator in the
+user-supplied buffer instead of the global state.
+
+Please note that it is no problem if several threads use the global
+state if all threads use the functions which take a pointer to an array
+containing the state. The random numbers are computed following the
+same loop but if the state in the array is different all threads will
+get an individuual random number generator.
+
+The user supplied buffer must be of type @code{struct drand48_data}.
+This type should be regarded as opaque and no member should be used
+directly.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is equivalent to the @code{drand48} function with the
+difference it does not modify the global random number generator
+parameters but instead the parameters is the buffer supplied by the
+buffer through the pointer @var{buffer}. The random number is return in
+the variable pointed to by @var{result}.
+
+The return value of the function indicate whether the call succeeded.
+If the value is less than @code{0} an error occurred and @var{errno} is
+set to indicate the problem.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
+The @code{erand48_r} function works like the @code{erand48} and it takes
+an argument @var{buffer} which describes the random number generator.
+The state of the random number genertor is taken from the @code{xsubi}
+array, the parameters for the congruential formula from the global
+random number generator data. The random number is return in the
+variable pointed to by @var{result}.
+
+The return value is non-negative is the call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is similar to @code{lrand48} and it takes a pointer to a
+buffer describing the state of the random number generator as a
+parameter just like @code{drand48}.
+
+If the return value of the function is non-negative the variable pointed
+to by @var{result} contains the result. Otherwise an error occurred.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
+The @code{nrand48_r} function works like @code{nrand48} in that it
+produces a random number in range @code{0} to @code{2^31}. But instead
+of using the global parameters for the congruential formula it uses the
+information from the buffer pointed to by @var{buffer}. The state is
+described by the values in @var{xsubi}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is similar to @code{mrand48} but as the other reentrant
+function it uses the random number generator described by the value in
+the buffer pointed to by @var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
+The @code{jrand48_r} function is similar to @code{jrand48}. But as the
+other reentrant functions of this function family it uses the
+congruential formula parameters from the buffer pointed to by
+@var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+Before any of the above functions should be used the buffer of type
+@code{struct drand48_data} should initialized. The easiest way is to
+fill the whole buffer with null bytes, e.g., using
+
+@smallexample
+memset (buffer, '\0', sizeof (struct drand48_data));
+@end smallexample
+
+@noindent
+Using any of the reetrant functions of this family now will
+automatically initialize the random number generator to the default
+values for the state and the parameters of the congruential formula.
+
+The other possibility is too use any of the functions which explicitely
+initialize the buffer. Though it might be obvious how to initialize the
+buffer from the data given as parameter from the function it is highly
+recommended to use these functions since the result might not always be
+what you expect.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
+The description of the random number generator represented by the
+information in @var{buffer} is initialized similar to what the function
+@code{srand48} does. The state is initialized from the paramter
+@var{seedval} and the paameters for the congruential formula are
+initialized to the default values.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
+This function is similar to @code{srand48_r} but like @code{seed48} it
+initializes all 48 bits of the state from the parameter @var{seed16v}.
+
+If the return value is non-negative the function call succeeded. It
+does not return a pointer to the previous state of the random number
+generator like the @code{seed48} function does. if the user wants to
+preserve the state for a later rerun s/he can copy the whole buffer
+pointed to by @var{buffer}.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
+This function initializes all aspects of the random number generator
+described in @var{buffer} by the data in @var{param}. Here it is
+especially true the function does more than just copying the contents of
+@var{param} of @var{buffer}. Some more actions are required and
+therefore it is important to use this function and not initialized the
+random number generator directly.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
diff --git a/manual/string.texi b/manual/string.texi
index 9d242b7c19..8f09ac9728 100644
--- a/manual/string.texi
+++ b/manual/string.texi
@@ -32,9 +32,10 @@ too.
* Search Functions:: Searching for a specific element or substring.
* Finding Tokens in a String:: Splitting a string into tokens by looking
for delimiters.
+* Encode Binary Data:: Encoding and Decoding of Binary Data.
@end menu
-@node Representation of Strings, String/Array Conventions, , String and Array Utilities
+@node Representation of Strings
@section Representation of Strings
@cindex string, representation of
@@ -99,7 +100,7 @@ checks for overflowing the array. Many of the library functions
an extra byte to hold the null character that marks the end of the
string.
-@node String/Array Conventions, String Length, Representation of Strings, String and Array Utilities
+@node String/Array Conventions
@section String and Array Conventions
This chapter describes both functions that work on arbitrary arrays or
@@ -132,7 +133,7 @@ other hand, when you are manipulating null-terminated strings it is
usually more convenient to use the @samp{str} functions, unless you
already know the length of the string in advance.
-@node String Length, Copying and Concatenation, String/Array Conventions, String and Array Utilities
+@node String Length
@section String Length
You can get the length of a string using the @code{strlen} function.
@@ -166,7 +167,7 @@ strlen (string)
@end smallexample
@end deftypefun
-@node Copying and Concatenation, String/Array Comparison, String Length, String and Array Utilities
+@node Copying and Concatenation
@section Copying and Concatenation
You can use the functions described in this section to copy the contents
@@ -470,7 +471,7 @@ BSD. Note that it is not as general as @code{memset}, because the only
value it can store is zero.
@end deftypefun
-@node String/Array Comparison, Collation Functions, Copying and Concatenation, String and Array Utilities
+@node String/Array Comparison
@section String/Array Comparison
@cindex comparing strings and arrays
@cindex string comparison functions
@@ -613,7 +614,7 @@ strncmp ("hello, world", "hello, stupid world!!!", 5)
This is an obsolete alias for @code{memcmp}, derived from BSD.
@end deftypefun
-@node Collation Functions, Search Functions, String/Array Comparison, String and Array Utilities
+@node Collation Functions
@section Collation Functions
@cindex collating strings
@@ -792,9 +793,9 @@ sort_strings_fast (char **array, int nstrings)
@end smallexample
@strong{Compatibility Note:} The string collation functions are a new
-feature of @w{ISO C}. Older C dialects have no equivalent feature.
+feature of @w{ISO C 89}. Older C dialects have no equivalent feature.
-@node Search Functions, Finding Tokens in a String, Collation Functions, String and Array Utilities
+@node Search Functions
@section Search Functions
This section describes library functions which perform various kinds
@@ -940,7 +941,7 @@ strpbrk ("hello, world", " \t\n,.;!?")
@c @end group
@end deftypefun
-@node Finding Tokens in a String, , Search Functions, String and Array Utilities
+@node Finding Tokens in a String
@section Finding Tokens in a String
@cindex tokenizing strings
@@ -1087,3 +1088,65 @@ token = strsep (&running, delimiters); /* token => "and" */
token = strsep (&running, delimiters); /* token => "punctuation" */
token = strsep (&running, delimiters); /* token => NULL */
@end smallexample
+
+@node Encode Binary Data
+@section Encode Binary Data
+
+To store or transfer binary data in environments which only support text
+one has to encode the binary data by mapping the input bytes to
+characters in the range allowed for storing or transfering. SVID
+systems (and nowadays XPG compliant systems) have such a function in the
+C library.
+
+@comment stdlib.h
+@comment XPG
+@deftypefun {char *} l64a (long int @var{n})
+This function encodes an input value with 32 bits using characters from
+the basic character set. Groups of 6 bits are encoded using the
+following table:
+
+@multitable {xxxxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx}
+@item @tab 0 @tab 1 @tab 2 @tab 3 @tab 4 @tab 5 @tab 6 @tab 7
+@item 0 @tab @code{.} @tab @code{/} @tab @code{0} @tab @code{1}
+ @tab @code{2} @tab @code{3} @tab @code{4} @tab @code{5}
+@item 8 @tab @code{6} @tab @code{7} @tab @code{8} @tab @code{9}
+ @tab @code{A} @tab @code{B} @tab @code{C} @tab @code{D}
+@item 16 @tab @code{E} @tab @code{F} @tab @code{G} @tab @code{H}
+ @tab @code{I} @tab @code{J} @tab @code{K} @tab @code{L}
+@item 24 @tab @code{M} @tab @code{N} @tab @code{O} @tab @code{P}
+ @tab @code{Q} @tab @code{R} @tab @code{S} @tab @code{T}
+@item 32 @tab @code{U} @tab @code{V} @tab @code{W} @tab @code{X}
+ @tab @code{Y} @tab @code{Z} @tab @code{a} @tab @code{b}
+@item 40 @tab @code{c} @tab @code{d} @tab @code{e} @tab @code{f}
+ @tab @code{g} @tab @code{h} @tab @code{i} @tab @code{j}
+@item 48 @tab @code{k} @tab @code{l} @tab @code{m} @tab @code{n}
+ @tab @code{o} @tab @code{p} @tab @code{q} @tab @code{r}
+@item 56 @tab @code{s} @tab @code{t} @tab @code{u} @tab @code{v}
+ @tab @code{w} @tab @code{x} @tab @code{y} @tab @code{z}
+@end multitable
+
+The function returns a pointer to a static buffer which contains the
+string representing of the encoding of @var{n}. To encoded a series of
+bytes the use should append the new string to the destination buffer.
+@emph{Warning:} Since a static buffer is used this function should not
+be used in multi-threaded programs. There is no thread-safe alternatice
+to this function in the C library.
+@end deftypefun
+
+To decode data produced with @code{l64a} the following function should be
+used.
+
+@deftypefun {long int} a64l (const char *@var{string})
+The parameter @var{string} should contain a string which was produced by
+a call to @code{l64a}. The function processes the next 6 characters and
+decodes the characters it finds according to the table above.
+Characters not in the conversion table are simply ignored. This is
+useful for breaking the information in lines in which case the end of
+line characters are simply ignored.
+
+The decoded number is returned at the end as a @code{long int} value.
+Consecutive calls to this function are possible but the caller must make
+sure the buffer pointer is update after each call to @code{a64l} since
+this function does not modify the buffer pointer. Every call consumes 6
+characters.
+@end deftypefun