diff options
| author | Ulrich Drepper <drepper@redhat.com> | 1998-07-13 12:29:13 +0000 |
|---|---|---|
| committer | Ulrich Drepper <drepper@redhat.com> | 1998-07-13 12:29:13 +0000 |
| commit | 7a68c94a5b8fb848590857f7d8c4a271bf4e8ea9 (patch) | |
| tree | f91b98eed7220f1cb3b29337ca432d323c7b7408 /manual/math.texi | |
| parent | ceb27555a1f637c048c7ec65a01f8122c3e79bf3 (diff) | |
| download | glibc-7a68c94a5b8fb848590857f7d8c4a271bf4e8ea9.tar.xz glibc-7a68c94a5b8fb848590857f7d8c4a271bf4e8ea9.zip | |
Update.
1998-07-10 18:14 -0400 Zack Weinberg <zack@rabi.phys.columbia.edu>
* manual/Makefile: Overhauled. Generate libc.texinfo from the
chapter files. Exorcise the chapters, chapters-incl mess.
Support inserting doc chapters from add-on modules.
(chapters): New variable.
(add-chapters): New variable.
(appendices): New variable.
(libc.texinfo): New target.
(clean): Fix bugs.
(realclean): Fix bugs.
* manual/texis.awk: New file.
* manual/libc-texinfo.sh: New file.
* manual/libc-texinfo.in: New file.
* manual/conf.texi (top @node): Remove next pointer.
* manual/lang.texi (top @node): Remove prev pointer.
* manual/job.texi (top @node): Add explicit pointers.
* manual/message.texi (top @node): Add explicit pointers.
* manual/nss.texi (top @node): Add explicit pointers.
* manual/process.texi (top @node): Add explicit pointers.
* manual/startup.texi (top @node): Add explicit pointers.
* manual/terminal.texi (top @node): Add explicit pointers.
* manual/users.texi (top @node): Add explicit pointers.
* manual/arith.texi: Add %MENU% tag.
* manual/conf.texi: Add %MENU% tag.
* manual/contrib.texi: Add %MENU% tag.
* manual/ctype.texi: Add %MENU% tag.
* manual/errno.texi: Add %MENU% tag.
* manual/filesys.texi: Add %MENU% tag.
* manual/header.texi: Add %MENU% tag.
* manual/install.texi: Add %MENU% tag.
* manual/intro.texi: Add %MENU% tag.
* manual/io.texi: Add %MENU% tag.
* manual/job.texi: Add %MENU% tag.
* manual/lang.texi: Add %MENU% tag.
* manual/llio.texi: Add %MENU% tag.
* manual/locale.texi: Add %MENU% tag.
* manual/maint.texi: Add %MENU% tag.
* manual/math.texi: Add %MENU% tag.
* manual/mbyte.texi: Add %MENU% tag.
* manual/memory.texi: Add %MENU% tag.
* manual/message.texi: Add %MENU% tag.
* manual/nss.texi: Add %MENU% tag.
* manual/pattern.texi: Add %MENU% tag.
* manual/pipe.texi: Add %MENU% tag.
* manual/process.texi: Add %MENU% tag.
* manual/search.texi: Add %MENU% tag.
* manual/setjmp.texi: Add %MENU% tag.
* manual/signal.texi: Add %MENU% tag.
* manual/socket.texi: Add %MENU% tag.
* manual/startup.texi: Add %MENU% tag.
* manual/stdio.texi: Add %MENU% tag.
* manual/string.texi: Add %MENU% tag.
* manual/sysinfo.texi: Add %MENU% tag.
* manual/terminal.texi: Add %MENU% tag.
* manual/time.texi: Add %MENU% tag.
* manual/users.texi: Add %MENU% tag.
1998-07-13 Ulrich Drepper <drepper@cygnus.com>
* sysdeps/unix/sysv/linux/i386/dl-procinfo.h (x86_cap_flags):
Update.
1998-07-11 Andreas Jaeger <aj@arthur.rhein-neckar.de>
* sysdeps/unix/sysv/linux/recvmsg.c (__libc_recvmsg): Use ANSI
style declaration to avoid warning.
* sysdeps/unix/sysv/linux/sendmsg.c (__libc_sendmsg): Likewise.
1998-07-04 Mark Kettenis <kettenis@phys.uva.nl>
* elf/rtld.c (process_dl_debug): Add missing continue.
1998-07-12 Mark Kettenis <kettenis@phys.uva.nl>
* elf/rtld.c (_dl_skip_args): Make global because the Hurd startup
code needs it.
1998-07-10 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* Makeconfig ($(common-objpfx)sysd-dirs): Write out definition of
sysd-dirs-done.
* Makerules: Don't generate version maps too early.
($(common-objpfx)sysd-versions): Force regeneration if the list of
subdirs has changed.
1998-07-10 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/dlfcn.h (DL_CALL_FCT): Use portable comma expression.
1998-07-11 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* iconv/gconv_db.c (gen_steps): Always set *handle and *nsteps.
* iconv/gconv_dl.c (__gconv_find_shlib): Correct use of tfind
return value.
1998-07-12 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/dl-open.c (dl_open_worker): New function.
(_dl_open): Call it to do the actual work while catching errors.
* elf/dl-close.c (_dl_close): Only call termination function if
the initialisation function was called.
1998-07-13 Ulrich Drepper <drepper@cygnus.com>
* libio/libioP.h (_IO_cleanup_registration_needed): Use __PMT.
Reported by Felix von Leitner <leitner@amdiv.de>.
1998-07-13 10:28 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* elf/rtld.c (process_dl_debug): Add missing continue.
1998-06-23 Mark Kettenis <kettenis@phys.uva.nl>
Diffstat (limited to 'manual/math.texi')
| -rw-r--r-- | manual/math.texi | 1395 |
1 files changed, 454 insertions, 941 deletions
diff --git a/manual/math.texi b/manual/math.texi index 1991bfbdb8..10b326287e 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -1,739 +1,129 @@ @c We need some definitions here. +@ifclear mult @ifhtml -@set mult · +@set mult · +@set infty ∞ +@set pie π @end ifhtml @iftex @set mult @cdot +@set infty @infty @end iftex @ifclear mult -@set mult x +@set mult * +@set infty oo +@set pie pi @end ifclear @macro mul @value{mult} @end macro -@iftex -@set infty @infty -@end iftex -@ifclear infty -@set infty oo -@end ifclear @macro infinity @value{infty} @end macro +@ifnottex +@macro pi +@value{pie} +@end macro +@end ifnottex +@end ifclear @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top +@c %MENU% Math functions, useful constants, random numbers @chapter Mathematics This chapter contains information about functions for performing mathematical computations, such as trigonometric functions. Most of these functions have prototypes declared in the header file -@file{math.h}. +@file{math.h}. The complex-valued functions are defined in +@file{complex.h}. @pindex math.h - -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. - +@pindex complex.h + +All mathematical functions which take a floating-point argument +have three variants, one each for @code{double}, @code{float}, and +@code{long double} arguments. The @code{double} versions are mostly +defined in @w{ISO C 89}. The @code{float} and @code{long double} +versions are from the numeric extensions to C included in @w{ISO C 9X}. + +Which of the three versions of a function should be used depends on the +situation. For most calculations, the @code{float} functions are the +fastest. On the other hand, the @code{long double} functions have the +highest precision. @code{double} is somewhere in between. It is +usually wise to pick the narrowest type that can accomodate your data. +Not all machines have a distinct @code{long double} type; it may be the +same as @code{double}. @menu -* Domain and Range Errors:: Detecting overflow conditions and the like. -* Exceptions in Math Functions:: Signalling exception in math functions. -* Mathematical Constants:: Precise numeric values for often used - constant. -* FP Comparison Functions:: Special functions to compare floating-point - numbers. -* FP Function Optimizations:: Fast code or small code. -* Trig Functions:: Sine, cosine, and tangent. -* Inverse Trig Functions:: Arc sine, arc cosine, and arc tangent. -* Exponents and Logarithms:: Also includes square root. -* Hyperbolic Functions:: Hyperbolic sine and friends. -* Pseudo-Random Numbers:: Functions for generating pseudo-random - numbers. +* Mathematical Constants:: Precise numeric values for often-used + constants. +* Trig Functions:: Sine, cosine, tangent, and friends. +* Inverse Trig Functions:: Arcsine, arccosine, etc. +* Exponents and Logarithms:: Also pow and sqrt. +* Hyperbolic Functions:: sinh, cosh, tanh, etc. +* Special Functions:: Bessel, gamma, erf. +* Pseudo-Random Numbers:: Functions for generating pseudo-random + numbers. +* FP Function Optimizations:: Fast code or small code. @end menu -@node Domain and Range Errors -@section Domain and Range Errors - -@cindex domain error -Many of the functions listed in this chapter are defined mathematically -over a domain that is only a subset of real numbers. For example, the -@code{acos} function is defined over the domain between @code{@minus{}1} and -@code{1}. If you pass an argument to one of these functions that is -outside the domain over which it is defined, the function sets -@code{errno} to @code{EDOM} to indicate a @dfn{domain error}. On -machines that support @w{IEEE 754} floating point, functions reporting -error @code{EDOM} also return a NaN. - -Some of these functions are defined mathematically to result in a -complex value over parts of their domains. The most familiar example of -this is taking the square root of a negative number. The functions in -this chapter take only real arguments and return only real values; -therefore, if the value ought to be nonreal, this is treated as a domain -error. - -@cindex range error -A related problem is that the mathematical result of a function may not -be representable as a floating point number. If magnitude of the -correct result is too large to be represented, the function sets -@code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and -returns a particular very large value (named by the macro -@code{HUGE_VAL}) or its negation (@code{@minus{}HUGE_VAL}). - -If the magnitude of the result is too small, a value of zero is returned -instead. In this case, @code{errno} might or might not be -set to @code{ERANGE}. - -The only completely reliable way to check for domain and range errors is -to set @code{errno} to @code{0} before you call the mathematical function -and test @code{errno} afterward. As a consequence of this use of -@code{errno}, use of the mathematical functions is not reentrant if you -check for errors. - -@c ### This is no longer true. --drepper -@c None of the mathematical functions ever generates signals as a result of -@c domain or range errors. In particular, this means that you won't see -@c @code{SIGFPE} signals generated within these functions. (@xref{Signal -@c Handling}, for more information about signals.) - -@comment math.h -@comment ISO -@deftypevr Macro double HUGE_VAL -An expression representing a particular very large number. On machines -that use @w{IEEE 754}/@w{IEEE 854} floating point format, the value is -``infinity''. On other machines, it's typically the largest positive -number that can be represented. - -The value of this macro is used as the return value from various -mathematical @code{double} returning functions in overflow situations. -@end deftypevr - -@comment math.h -@comment ISO -@deftypevr Macro float HUGE_VALF -This macro is similar to the @code{HUGE_VAL} macro except that it is -used by functions returning @code{float} values. - -This macro is introduced in @w{ISO C 9X}. -@end deftypevr - -@comment math.h -@comment ISO -@deftypevr Macro {long double} HUGE_VALL -This macro is similar to the @code{HUGE_VAL} macro except that it is -used by functions returning @code{long double} values. The value is -only different from @code{HUGE_VAL} if the architecture really supports -@code{long double} values. - -This macro is introduced in @w{ISO C 9X}. -@end deftypevr - - -A special case is the @code{ilogb} function @pxref{Exponents and -Logarithms}. Since the return value is an integer value, one cannot -compare with @code{HUGE_VAL} etc. Therefore two further values are -defined. - -@comment math.h -@comment ISO -@deftypevr Macro int FP_ILOGB0 -This value is returned by @code{ilogb} if the argument is @code{0}. The -numeric value is either @code{INT_MIN} or @code{-INT_MAX}. - -This macro is introduced in @w{ISO C 9X}. -@end deftypevr - -@comment math.h -@comment ISO -@deftypevr Macro int FP_ILOGBNAN -This value is returned by @code{ilogb} if the argument is @code{NaN}. The -numeric value is either @code{INT_MIN} or @code{INT_MAX}. - -This macro is introduced in @w{ISO C 9X}. -@end deftypevr - - -For more information about floating-point representations and limits, -see @ref{Floating Point Parameters}. In particular, the macro -@code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many -uses other than testing for an error in a mathematical function. - - -@node Exceptions in Math Functions -@section Exceptions in Math Functions -@cindex exception -@cindex signal - -Due to the restrictions in the size of the floating-point number -representation or the limitation of the input range of certain functions -some of the mathematical operations and functions have to signal -exceptional situations. The @w{IEEE 754} standard specifies which -exceptions have to be supported and how they can be handled. - -@w{IEEE 754} specifies two actions for floating-point exception: taking -a trap or continuing without doing so. If the trap is taken a -(possibly) user defined trap handler is called and this function can -correct the argument or react somehow else on the call. If the trap -handler returns, its return value is taken as the result of the -operation. - -If no trap handler is called each of the known exceptions has a default -action. This consists of setting a corresponding bit in the -floating-point status word to indicate which kind of exception was -raised and to return a default value, which depends on the exception -(see the table below). - -@noindent -The exceptions defined in @w{IEEE 754} are: - -@table @samp -@item Invalid Operation -This exception is raised if the given operands are invalid for the -operation to be performed. Examples are -(see @w{IEEE 754}, @w{section 7}): -@enumerate -@item -Any operation on a signalling NaN. -@item -Addition or subtraction; magnitude subtraction of infinities such as -@math{(+@infinity{}) + (-@infinity{})}. -@item -Multiplication: -@math{0 @mul{} @infinity{}}. - -@item -Division: @math{0/0} or @math{@infinity{}/@infinity{}}. - -@item -Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is -infinite. -@item -Square root if the operand is less then zero. -@item -Conversion of an internal floating-point number to an integer or to a -decimal string when overflow, infinity, or NaN precludes a faithful -representation in that format and this cannot otherwise be signaled. -@item -Conversion of an unrecognizable input string. -@item -Comparison via predicates involving @math{<} or @math{>}, without -@code{?}, when the operands are @dfn{unordered}. (@math{?>} means the -unordered greater relation, @xref{FP Comparison Functions}). -@end enumerate - -If the exception does not cause a trap handler to be called the result -of the operation is taken as a quiet NaN. - -@item Division by Zero -This exception is raised if the divisor is zero and the dividend is a -finite nonzero number. If no trap occurs the result is either -@math{+@infinity{}} or @math{-@infinity{}}, depending on the -signs of the operands. - -@item Overflow -This exception is signalled whenever the result cannot be represented -as a finite value in the precision format of the destination. If no trap -occurs the result depends on the sign of the intermediate result and the -current rounding mode (@w{IEEE 754}, @w{section 7.3}): -@enumerate -@item -Round to nearest carries all overflows to @math{@infinity{}} -with the sign of the intermediate result. -@item -Round toward @math{0} carries all overflows to the precision's largest -finite number with the sign of the intermediate result. -@item -Round toward @math{-@infinity{}} carries positive overflows to the -precision's largest finite number and carries negative overflows to -@math{-@infinity{}}. - -@item -Round toward @math{@infinity{}} carries negative overflows to the -precision's most negative finite number and carries positive overflows -to @math{@infinity{}}. -@end enumerate - -@item Underflow -The underflow exception is created when an intermediate result is too -small for the operation or if the operations result rounded to the -destination precision causes a loss of accuracy by approximating the -result by denormalized numbers. - -When no trap is installed for the underflow exception, underflow shall -be signaled (via the underflow flag) only when both tininess and loss of -accuracy have been detected. If no trap handler is installed the -operation continues with an inprecise small value or zero if the -destination precision cannot hold the small exact result. - -@item Inexact -This exception is signalled if the rounded result is not exact (such as -computing the square root of two) or the result overflows without an -overflow trap. -@end table - -To control whether an exception causes a trap to occur all @w{IEEE 754} -conformant floating-point implementations (either hardware or software) -have a control word. By setting specific bits for each exception in -this control word the programmer can decide whether a trap is wanted or -not. - -@w{ISO C 9X} introduces a set of function which can be used to control -exceptions. There are functions to manipulate the control word, to -query the status word or to save and restore the whole state of the -floating-point unit. There are also functions to control the rounding -mode used. - -@menu -* Status bit operations:: Manipulate the FP status word. -* FPU environment:: Controlling the status of the FPU. -* Rounding Modes:: Controlling the rounding mode. -@end menu - -@node Status bit operations -@subsection Controlling the FPU status word - -To control the five types of exceptions defined in @w{IEEE 754} some -functions are defined which abstract the interface to the FPU. The -actual implementation can be very different, depending on the underlying -hardware or software. - -To address the single exception the @file{fenv.h} headers defines a -number of macros: - -@vtable @code -@comment fenv.h -@comment ISO -@item FE_INEXACT -Represents the inexact exception iff the FPU supports this exception. -@comment fenv.h -@comment ISO -@item FE_DIVBYZERO -Represents the divide by zero exception iff the FPU supports this exception. -@comment fenv.h -@comment ISO -@item FE_UNDERFLOW -Represents the underflow exception iff the FPU supports this exception. -@comment fenv.h -@comment ISO -@item FE_OVERFLOW -Represents the overflow exception iff the FPU supports this exception. -@comment fenv.h -@comment ISO -@item FE_INVALID -Represents the invalid exception iff the FPU supports this exception. -@end vtable - -The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros -which are supported by the FP implementation. - -Each of the supported exception flags can either be set or unset. The -@w{ISO C 9X} standard defines functions to set, unset and test the -status of the flags. - -@comment fenv.h -@comment ISO -@deftypefun void feclearexcept (int @var{excepts}) -This function clears all of the supported exception flags denoted by -@var{excepts} in the status word. -@end deftypefun - -To safe the current status of the flags in the status word @file{fenv.h} -defines the type @code{fexcept_t} which can hold all the information. -The following function can be used to retrieve the current setting. - -@comment fenv.h -@comment ISO -@deftypefun void fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts}) -Store in the variable pointed to by @var{flagp} an -implementation-defined value representing the current setting of the -exception flags indicated by the parameter @var{excepts}. -@end deftypefun - -@noindent -To restore the previously saved values one can use this function: - -@comment fenv.h -@comment ISO -@deftypefun void fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts}) -Restore from the variable pointed to by @var{flagp} the setting of the -flags for the exceptions denoted by the value of the parameter -@var{excepts}. -@end deftypefun - -The last function allows to query the current status of the flags. The -flags can be set either explicitely (using @code{fesetexceptflag} or -@code{feclearexcept}) or by a floating-point operation which happened -before. Since the flags are accumulative, the flags must be explicitely -reset using @code{feclearexcept} if one wants to test for a certain -exceptions raised by a specific piece of code. - -@comment fenv.h -@comment ISO -@deftypefun int fetestexcept (int @var{excepts}) -Test whether a subset of the flags indicated by the parameter -@var{except} is currently set. If yes, a nonzero value is returned -which specifies which exceptions are set. Otherwise the result is zero. -@end deftypefun - -@noindent -Code which uses the @code{fetestexcept} function could look like this: - -@smallexample -@{ - double f; - int raised; - feclearexcept (FE_ALL_EXCEPT); - f = compute (); - raised = fetestexcept (FE_OVERFLOW | FE_INVALID); - if (raised & FE_OVERFLOW) @{ /* ... */ @} - if (raised & FE_INVALID) @{ /* ... */ @} - /* ... */ -@} -@end smallexample - -Please note that the return value of @code{fetestexcept} is @code{int} -but this does not mean that the @code{fexcept_t} type is generally -representable as an integer. These are completely independent types. - - -@node FPU environment -@subsection Controlling the Floating-Point environment - -It is sometimes necessary so save the complete status of the -floating-point unit for a certain time to perform some completely -different actions. Beside the status of the exception flags, the -control word for the exceptions and the rounding mode can be saved. - -The file @file{fenv.h} defines the type @code{fenv_t}. The layout of a -variable of this type is implementation defined but the variable is able -to contain the complete status information. To fill a variable of this -type one can use this function: - -@comment fenv.h -@comment ISO -@deftypefun void fegetenv (fenv_t *@var{envp}) -Store the current floating-point environment in the object pointed to by -@var{envp}. -@end deftypefun - -@noindent -Another possibility which is useful in several situations is - -@comment fenv.h -@comment ISO -@deftypefun int feholdexcept (fenv_t *@var{envp}) -Store the current floating-point environment in the object pointed to by -@var{envp}. Afterwards, all exception flags are cleared and if -available a mode is installed which continues on all exceptions and does -not cause a trap to occur. In this case a nonzero value is returned. - -If the floating-point implementation does not support such a non-stop -mode, the return value is zero. -@end deftypefun - -The functions which allow a state of the floating-point unit to be -restored can take two kinds of arguments: - -@itemize @bullet -@item -Pointers to @code{fenv_t} objects which were initialized previously by a -call to @code{fegetenv} or @code{feholdexcept}. -@item -@vindex FE_DFL_ENV -The special macro @code{FE_DFL_ENV} which represents the floating-point -environment as it was available at program start. -@item -Implementation defined macros with names starting with @code{FE_}. - -@vindex FE_NOMASK_ENV -If possible, the GNU C Library defines a macro @code{FE_NOMASK_ENV} -which represents an environment where no exceptions are masked, so every -exception raised causes a trap to occur. You can test for this macro -using @code{#ifdef}. - -Some platforms might define other predefined environments. -@end itemize - -@noindent -To set any of the environments there are two functions defined. - -@deftypefun void fesetenv (const fenv_t *@var{envp}) -Establish the floating-point environment described in the object pointed -to by @var{envp}. Even if one or more exceptions flags in the restored -environment are set no exception is raised. -@end deftypefun - -In some situations the previous status of the exception flags must not -simply be discarded and so this function is useful: - -@deftypefun void feupdateenv (const fenv_t *@var{envp}) -The current status of the floating-point unit is preserved in some -automatic storage before the environment described by the object pointed -to by @var{envp} is installed. Once this is finished all exceptions set -in the original environment which is saved in the automatic storage, is -raised. -@end deftypefun - -This function can be used to execute a part of the program with an -environment which masks all exceptions and before switching back remove -unwanted exception and raise the remaining exceptions. - - -@node Rounding Modes -@subsection Rounding modes of the Floating-Point Unit - -@w{IEEE 754} defines four different rounding modes. If the rounding -mode is supported by the floating-point implementation the corresponding -of the following macros is defined: - -@table @code -@comment fenv.h -@comment ISO -@vindex FE_TONEAREST -@item FE_TONEAREST -Round to nearest. This is the default mode and should always be used -except when a different mode is explicitely required. Only rounding to -nearest guarantees numeric stability of the computations. - -@comment fenv.h -@comment ISO -@vindex FE_UPWARD -@item FE_UPWARD -Round toward @math{+@infinity{}}. - -@comment fenv.h -@comment ISO -@vindex FE_DOWNWARD -@item FE_DOWNWARD -Round toward @math{-@infinity{}}. |
