aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
Diffstat (limited to 'manual')
-rw-r--r--manual/arith.texi16
-rw-r--r--manual/errno.texi2
-rw-r--r--manual/libc.texinfo2
-rw-r--r--manual/math.texi757
-rw-r--r--manual/pattern.texi3
-rw-r--r--manual/socket.texi38
-rw-r--r--manual/texinfo.tex22
-rw-r--r--manual/time.texi29
8 files changed, 809 insertions, 60 deletions
diff --git a/manual/arith.texi b/manual/arith.texi
index 1268e37..7f8c205 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -201,7 +201,7 @@ better to use those in this section which are introduced in the @w{ISO C
@comment math.h
@comment ISO
-@deftypefun int fpclassify (@emph{float-type} @var{x})
+@deftypefn {Macro} 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:
@@ -227,7 +227,7 @@ plain floating-point number without special meaning.
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
+@end deftypefn
The remainder of this section introduces some more specific functions.
They might be implemented faster than the call to @code{fpclassify} and
@@ -236,7 +236,7 @@ should be used (and not @code{fpclassify}).
@comment math.h
@comment ISO
-@deftypefun int isfinite (@emph{float-type} @var{x})
+@deftypefn {Macro} 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
@@ -247,11 +247,11 @@ not plus or minus infinity and not NaN. I.e., it could be implemented as
@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
+@end deftypefn
@comment math.h
@comment ISO
-@deftypefun int isnormal (@emph{float-type} @var{x})
+@deftypefn {Macro} 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
@@ -259,11 +259,11 @@ could be implemented as
@smallexample
(fpclassify (x) == FP_NORMAL)
@end smallexample
-@end deftypefun
+@end deftypefn
@comment math.h
@comment ISO
-@deftypefun int isnan (@emph{float-type} @var{x})
+@deftypefn {Macro} 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
@@ -287,7 +287,7 @@ situation the function be absolutely necessary one can use
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
+@end deftypefn
@node Operations on Complex
diff --git a/manual/errno.texi b/manual/errno.texi
index 800b039..c073deb 100644
--- a/manual/errno.texi
+++ b/manual/errno.texi
@@ -430,7 +430,7 @@ until some external condition makes it possible to read, write, or
connect (whatever the operation). You can use @code{select} to find out
when the operation will be possible; @pxref{Waiting for I/O}.
-@strong{Portability Note:} In older many Unix systems, this condition
+@strong{Portability Note:} In many older Unix systems, this condition
was indicated by @code{EWOULDBLOCK}, which was a distinct error code
different from @code{EAGAIN}. To make your program portable, you should
check for both codes and treat them the same.
diff --git a/manual/libc.texinfo b/manual/libc.texinfo
index 2d79d96..cb1769f 100644
--- a/manual/libc.texinfo
+++ b/manual/libc.texinfo
@@ -19,7 +19,7 @@
@c sold 0.06/1.09, print run out 21may96
@set EDITION 0.07 DRAFT
@set VERSION 2.00 Beta
-@set UPDATED 20 Jun 1997
+@set UPDATED 04 Aug 1997
@set ISBN 1-882114-53-1
@ifinfo
diff --git a/manual/math.texi b/manual/math.texi
index e2adccd..d4449bb 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -1,3 +1,11 @@
+@c We need some definitions here.
+@iftex
+@set TEXFORMULAS
+@end iftex
+@ifhtml
+@set cdot ·
+@end ifhtml
+
@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
@chapter Mathematics
@@ -25,13 +33,18 @@ in case of double using @code{double} is a good compromise.
@menu
-* Domain and Range Errors:: Detecting overflow conditions and the like.
-* 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.
+* 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.
+* 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.
@end menu
@node Domain and Range Errors
@@ -72,11 +85,11 @@ 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 isn't always true at the moment....
-None of the mathematical functions ever generates signals as a result of
-domain or range errors. In particular, this means that you won't see
-@code{SIGFPE} signals generated within these functions. (@xref{Signal
-Handling}, for more information about signals.)
+@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
@@ -111,13 +124,662 @@ This macro is introduced in @w{ISO C 9X}.
@end deftypevr
-@comment
+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
+@iftex
+@tex
+$(+\infty) + (-\infty)$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{(+oo) + (-oo)}.
+@end ifclear
+@item
+Multiplication:
+@iftex
+@tex
+$0 \cdot \infty$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@ifset cdot
+@math{0 @value{cdot} oo}.
+@end ifset
+@ifclear cdot
+@math{0 x oo}.
+@end ifclear
+@end ifclear
+
+@item
+Division: @math{0/0} or
+@iftex
+@tex
+$\infty/\infty$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{oo/oo}.
+@end ifclear
+
+@item
+Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
+infinite.
+@item
+Squre root if the operand is less then zero.
+@item
+Conversion of an internal floating-point number to an integer or toa
+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 of the devisor is zero and the dividend is a
+finite nonzero number. If no trap occurs the result is either
+@iftex
+@tex
+$\infty$
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{+oo}
+@end ifclear
+or
+@iftex
+@tex
+$-\infty$
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{-oo}
+@end ifclear
+, depending on the
+signs of the operands.
+
+@item Overflow
+This exception is signalled whenever if the result cannot be represented
+as a finite value in the destination precision's format. 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
+@iftex
+@tex
+$\infty$
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{oo}
+@end ifclear
+with the sign of the intermediate result.
+@item
+Round towards @math{0} carries all overflows to the precision's largest
+finite number with the sign of the intermediate result.
+@item
+Round towards
+@iftex
+@tex
+$-\infty$
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{-oo}
+@end ifclear
+carries positive overflows to the
+precision's largest finite number and carries negative overflows to
+@iftex
+@tex
+$-\infty$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{-oo}.
+@end ifclear
+
+@item
+Round towards
+@iftex
+@tex
+$\infty$
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{oo}
+@end ifclear
+carries negative overflows to the
+precision's most negative finite number and carries positive overflows
+to
+@iftex
+@tex
+$\infty$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{oo}.
+@end ifclear
+@end enumerate
+
+@item Underflow
+The underflow exception is created when a 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 witht he inprecise small value or zero if the
+destination precision cannot hold the small exact result.
+
+@item Inexact
+This exception is signaled 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 implementation (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 macros:
+
+@vtable @code
+@comment fenv.h
+@comment ISO
+@item FE_INEXACT
+Represent the inexact exception iff the FPU supports this exception.
+@comment fenv.h
+@comment ISO
+@item FE_DIVBYZERO
+Represent the divide by zero exception iff the FPU supports this exception.
+@comment fenv.h
+@comment ISO
+@item FE_UNDERFLOW
+Represent the underflow exception iff the FPU supports this exception.
+@comment fenv.h
+@comment ISO
+@item FE_OVERFLOW
+Represent the overflow exception iff the FPU supports this exception.
+@comment fenv.h
+@comment ISO
+@item FE_INVALID
+Represent 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 flag 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 functions 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 functions:
+
+@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 safed.
+
+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 informations. 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 is 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 exception and does
+not cause a trap to occur. In ths 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
+Pointed to objects which previously were initialized 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 exception is masked and so each
+raised exception causes a trap to occur. Whether this macro is available can easily be tested using @code{#ifdef}.
+
+Some platforms might define further 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:
+
+@vtable @code
+@comment fenv.h
+@comment ISO
+@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
+@item FE_UPWARD
+Round toward
+@iftex
+@tex
+$+\infty$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{+oo}.
+@end ifclear
+
+@comment fenv.h
+@comment ISO
+@item FE_DOWNWARD
+Round toward
+@iftex
+@tex
+$-\infty$.
+@end tex
+@end iftex
+@ifclear TEXFORMULAS
+@math{-oo}.
+@end ifclear
+
+@comment fenv.h
+@comment ISO
+@item FE_TOWARDZERO
+Round toward zero.
+@end vtable
+
+At any time one of the four rounding modes above is selected. To get
+information about the currently selected mode one can use this function:
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fegetround (void)
+Return the currently selected rounding mode, represented by one of the
+values of the defined rouding mode macros.
+@end deftypefun
+
+@noindent
+To set a specific rounding mode the next function can be used.
+
+@comment fenv.h
+@comment ISO
+@deftypefun int fesetround (int @var{round})
+Change the currently selected rounding mode to the mode described by the
+parameter @var{round}. If @var{round} does not correspond to one of the
+supported rounding modes nothing is changed.
+
+The function return a nonzero value iff the requested rounding mode can
+be established. Otherwise zero is returned.
+@end deftypefun
+
+Changing the rounding mode can be necessary for various reasons. But
+changing the mode only to round a given number normally is no good idea.
+The standard defines a set of functions which can be used to round an
+argument according to some rules and for all of the rounding modes there
+is a corresponding function.
+
+If a large set of number has to be rounded it might be good to change
+the rounding mode and do not use the function the library provides. So
+the perhaps necessary switching of the rounding mode in the library
+function can be avoided. But since not all rounding modes are
+guaranteed to exist on any platform this possible implementation cannot
+be portably used. A default method has to be implemented as well.
+
+
+@node Mathematical Constants
+@section Predefined Mathematical Constants
+@cindex constants
+@cindex mathematical constants
+
+The header @file{math.h} defines a series of mathematical constants if
+@code{_BSD_SOURCE} or a more general feature select macro is defined
+before including this file. All values are defined as preprocessor
+macros starting with @code{M_}. The collection includes:
+
+@vtable @code
+@item M_E
+The value is that of the base of the natural logarithm.
+@item M_LOG2E
+The value is computed as the logarithm to base @code{2} of @code{M_E}.
+@item M_LOG10E
+The value is computed as the logarithm to base @code{10} of @code{M_E}.
+@item M_LN2
+The value is computed as the natural logarithm of @code{2}.
+@item M_LN10
+The value is computed as the natural logarithm of @code{10}.
+@item M_PI
+The value is those of the number pi.
+@item M_PI_2
+The value is those of the number pi divided by two.
+@item M_PI_4
+The value is those of the number pi divided by four.
+@item M_1_PI
+The value is the reziprocal of the value of the number pi.
+@item M_2_PI
+The value is two times the reziprocal of the value of the number pi.
+@item M_2_SQRTPI
+The value is two times the reziprocal of the square root of the number pi.
+@item M_SQRT2
+The value is the square root of the value of the number pi.
+@item M_SQRT1_2
+The value is the reziprocal of the square root of the value of the number pi.
+@end vtable
+
+ALl values are defined as @code{long double} values unless the compiler
+does not support this type or @code{__STDC__} is not defined (both is
+unlikey). Historically the numbers were @code{double} values and some
+old code still relies on this so you might want to add explizit casts if
+the extra precision of the @code{long double} value is not needed. One
+critical case are functions with a variable number of arguments, such as
+@code{printf}.
+
+@vindex PI
+@emph{Note:} Some programs use a constant named @code{PI} which has the
+same value as @code{M_PI}. This probably derives from Stroustroup's
+book about his C++ programming language where this value is used in
+examples (and perhaps some AT&T headers contain this value). But due to
+possible name space problems (@code{PI} is a quite frequently used name)
+this value is not added to @file{math.h}. Every program should use
+@code{M_PI} instead or add on the the compiler command line
+@code{-DPI=M_PI}.
+
+
+@node FP Comparison Functions
+@section Floating-Point Comparison Functions
+@cindex unordered comparison
+
+The @w{IEEE 754} standards defines s'a set of functions which allows to
+compare even those numbers which normally would cause an exception to be
+raised since they are unordered. E.g., the expression
+
+@smallexample
+int v = a < 1.0;
+@end smallexample
+
+@noindent
+would raise an exception if @var{a} would be a NaN. Functions to
+compare unordered numbers are part of the FORTRAN language for a long
+time and the extensions in @w{ISO C 9X} finally introduce them as well
+for the C programming language.
+
+All of the operations are implemented as macros which allow their
+arguments to be of either @code{float}, @code{double}, or @code{long
+double} type.
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+This macro determines whether the argument @var{x} is greater than
+@var{y}. This is equivalent to @math{(x) > (y)} but no exception is
+raised if @var{x} or @var{y} are unordered.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+This macro determines whether the argument @var{x} is greater than or
+equal to @var{y}. This is equivalent to @math{(x) >= (y)} but no
+exception is raised if @var{x} or @var{y} are unordered.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+This macro determines whether the argument @var{x} is less than @var{y}.
+This is equivalent @math{(x) < (y)} but no exception is raised if
+@var{x} or @var{y} are unordered.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+This macro determines whether the argument @var{x} is less than or equal
+to @var{y}. This is equivalent to @math{(x) <= (y)} but no exception
+is raised if @var{x} or @var{y} are unordered.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+This macro determines whether the argument @var{x} is less or greater
+than @var{y}. This is equivalent to @math{(x) < (y) || (x) > (y)}
+(except that @var{x} and @var{y} are only evaluated once) but no
+exception is raised if @var{x} or @var{y} are unordered.
+@end deftypefn
+
+@comment math.h
+@comment ISO
+@deftypefn {Macro} int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
+This macro determines whether its arguments are unordered.
+@end deftypefn
+
+All the macros are defined in a way to ensure that both arguments are
+evaluated exactly once and so they can be used exactly like the builtin
+operators.
+
+On several platform these macros are mapped on very efficient functions
+the processor understands. But on machines missing these functions, the
+macros above might be rather slow. So it is best to use the builtin
+operators unless it is necessary to use unordered comparisons.
+
+
@node Trig Functions
@section Trigonometric Functions
@cindex trigonometric functions
@@ -128,11 +790,9 @@ that pi radians equals 180 degrees.
@cindex pi (trigonometric constant)
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:
+(@pxref{Mathematical Constants}) when BSD compliance is required
+(@pxref{Feature Test Macros}). In case it is not possible to use this
+predefined macro one easily can define it:
@smallexample
#define M_PI 3.14159265358979323846264338327
@@ -458,6 +1118,60 @@ different base, it is similar to the @code{log} function. In fact,
@comment math.h
@comment ISO
+@deftypefun double logb (double @var{x})
+@deftypefunx float logbf (float @var{x})
+@deftypefunx {long double} logbl (long double @var{x})
+These functions extract the exponent of @var{x} and return it as a
+signed integer value. If @var{x} is zero, a range error may occur.
+
+A special case are subnormal numbers (if supported by the floating-point
+format). The exponent returned is not the actual value from @var{x}.
+Instead the number is first normalized as if the range of the exponent
+field is large enough.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int ilogb (double @var{x})
+@deftypefunx int ilogbf (float @var{x})
+@deftypefunx int ilogbl (long double @var{x})
+These functions are equivalent to the corresponding @code{logb}
+functions except that the values are returned as signed integer values.
+Since integer values cannot represent infinity and NaN, there are some
+special symbols defined to help detect these situations.
+
+@vindex FP_ILOGB0
+@vindex FP_ILOGBNAN
+@code{ilogb} returns @code{FP_ILOGB0} if @var{x} is @code{0} and it
+returns @code{FP_ILOGBNAN} if @var{x} is @code{NaN}. These values are
+system specific and no fixed value is assigned. More concrete, these
+values might even have the same value. So a piece of code handling the
+result of @code{ilogb} could look like this:
+
+@smallexample
+i = ilogb (f);
+if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
+ @{
+ if (isnan (f))
+ @{
+ /* @r{Handle NaN.} */
+ @}
+ else if (f == 0.0)
+ @{
+ /* @r{Handle 0.0.} */
+ @}
+ else
+ @{
+ /* @r{Some other value with large exponent,}
+ @r{perhaps +Inf.} */
+ @}
+ @}
+@end smallexample
+
+@end deftypefun
+
+@comment math.h
+@comment ISO
@deftypefun double pow (double @var{base}, double @var{power})
@deftypefunx float powf (float @var{base}, float @var{power})
@deftypefunx {long double} powl (long double @var{base}, long double @var{power})
@@ -758,6 +1472,7 @@ 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
@@ -928,7 +1643,7 @@ since the state consists of a 48 bit array.
@comment stdlib.h
@comment SVID
-@deftypefun double drand48 ()
+@deftypefun double drand48 (void)
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.
@@ -953,7 +1668,7 @@ using to get reproducible results.
@comment stdlib.h
@comment SVID
-@deftypefun {long int} lrand48 ()
+@deftypefun {long int} lrand48 (void)
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.
@@ -977,7 +1692,7 @@ the first call to get reproducible results.
@comment stdlib.h
@comment SVID
-@deftypefun {long int} mrand48 ()
+@deftypefun {long int} mrand48 (void)
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).
diff --git a/manual/pattern.texi b/manual/pattern.texi
index 020a40e..1decfe3 100644
--- a/manual/pattern.texi
+++ b/manual/pattern.texi
@@ -1202,9 +1202,6 @@ expand_and_execute (const char *program, const char *options)
@}
@end smallexample
-In practice, since @code{wordexp} is executed by running a subshell, it
-would be faster to do this by concatenating the strings with spaces
-between them and running that as a shell command using @samp{sh -c}.
@c No sense finishing this for here.
@ignore
diff --git a/manual/socket.texi b/manual/socket.texi
index cc39bec..0353eb7 100644
--- a/manual/socket.texi
+++ b/manual/socket.texi
@@ -128,6 +128,28 @@ protocol} which you can request by specifying 0 as the protocol
number. And that's what you should normally do---use the default.
@end itemize
+Throughout the following description at various places
+variables/parameters to denote sizes are required. And here the trouble
+starts. In the first implementations the type of these variables was
+simply @code{int}. This type was on almost all machines of this time 32
+bits wide and so a de-factor standard required 32 bit variables. This
+is important since references to variables of this type are passed to
+the kernel.
+
+But now the POSIX people came and unified the interface with their words
+"all size values are of type @code{size_t}". But on 64 bit machines
+@code{size_t} is 64 bits wide and so variable references are not anymore
+possible.
+
+A solution provides the Unix98 specification which finally introduces a
+type @code{socklen_t}. This type is used in all of the cases in
+previously changed to use @code{size_t}. The only requirement of this
+type is that it is an unsigned type of at least 32 bits. Therefore,
+implementations which require references to 32 bit variables be passed
+can be as happy as implementations which right from the start of 64 bit
+values.
+
+
@node Communication Styles
@section Communication Styles
@@ -358,7 +380,7 @@ For examples of use, see @ref{File Namespace}, or see @ref{Inet Example}.
@comment sys/socket.h
@comment BSD
-@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, size_t @var{length})
+@deftypefun int bind (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
The @code{bind} function assigns an address to the socket
@var{socket}. The @var{addr} and @var{length} arguments specify the
address; the detailed format of the address depends on the namespace.
@@ -406,7 +428,7 @@ Internet socket. The prototype for this function is in the header file
@comment sys/socket.h
@comment BSD
-@deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, size_t *@var{length-ptr})
+@deftypefun int getsockname (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
The @code{getsockname} function returns information about the
address of the socket @var{socket} in the locations specified by the
@var{addr} and @var{length-ptr} arguments. Note that the
@@ -1688,7 +1710,7 @@ program must do, using the @code{connect} function, which is declared in
@comment sys/socket.h
@comment BSD
-@deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, size_t @var{length})
+@deftypefun int connect (int @var{socket}, struct sockaddr *@var{addr}, socklen_t @var{length})
The @code{connect} function initiates a connection from the socket
with file descriptor @var{socket} to the socket whose address is
specified by the @var{addr} and @var{length} arguments. (This socket
@@ -1833,7 +1855,7 @@ queue.
@comment sys/socket.h
@comment BSD
-@deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, size_t *@var{length-ptr})
+@deftypefun int accept (int @var{socket}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
This function is used to accept a connection request on the server
socket @var{socket}.
@@ -2327,7 +2349,7 @@ more information about the @code{connect} function.
@comment sys/socket.h
@comment BSD
-@deftypefun int sendto (int @var{socket}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t @var{length})
+@deftypefun int sendto (int @var{socket}, void *@var{buffer}. size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t @var{length})
The @code{sendto} function transmits the data in the @var{buffer}
through the socket @var{socket} to the destination address specified
by the @var{addr} and @var{length} arguments. The @var{size} argument
@@ -2356,7 +2378,7 @@ also tells you where it was sent from. This function is declared in
@comment sys/socket.h
@comment BSD
-@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, size_t *@var{length-ptr})
+@deftypefun int recvfrom (int @var{socket}, void *@var{buffer}, size_t @var{size}, int @var{flags}, struct sockaddr *@var{addr}, socklen_t *@var{length-ptr})
The @code{recvfrom} function reads one packet from the socket
@var{socket} into the buffer @var{buffer}. The @var{size} argument
specifies the maximum number of bytes to be read.
@@ -2583,7 +2605,7 @@ They are declared in @file{sys/socket.h}.
@comment sys/socket.h
@comment BSD
-@deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, size_t *@var{optlen-ptr})
+@deftypefun int getsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t *@var{optlen-ptr})
The @code{getsockopt} function gets information about the value of
option @var{optname} at level @var{level} for socket @var{socket}.
@@ -2613,7 +2635,7 @@ The @var{optname} doesn't make sense for the given @var{level}.
@comment sys/socket.h
@comment BSD
-@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, size_t @var{optlen})
+@deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen})
This function is used to set the socket option @var{optname} at level
@var{level} for socket @var{socket}. The value of the option is passed
in the buffer @var{optval}, which has size @var{optlen}.
diff --git a/manual/texinfo.tex b/manual/texinfo.tex
index 813d3c2..35bc0b0 100644
--- a/manual/texinfo.tex
+++ b/manual/texinfo.tex
@@ -1,5 +1,5 @@
%% TeX macros to handle Texinfo files.
-%% $Id: texinfo.tex,v 2.211 1997/07/28 21:55:24 drepper Exp $
+%% $Id: texinfo.tex,v 2.212 1997/08/04 14:14:11 drepper Exp $
% Copyright (C) 1985, 86, 88, 90, 91, 92, 93,
% 94, 95, 96, 97 Free Software Foundation, Inc.
@@ -36,7 +36,7 @@
% This automatically updates the version number based on RCS.
\def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}}
-\deftexinfoversion$Revision: 2.211 $
+\deftexinfoversion$Revision: 2.212 $
\message{Loading texinfo package [Version \texinfoversion]:}
% If in a .fmt file, print the version number
@@ -121,7 +121,7 @@
% For @cropmarks command.
% Do @cropmarks to get crop marks.
-%
+%
\newif\ifcropmarks
\let\cropmarks = \cropmarkstrue
%
@@ -1396,10 +1396,6 @@ where each line of input produces a line of output.}
% the catcodes are wrong for parsearg to work.)
\gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}
-% If you use @setkbdinputexample, then @kbd produces slanted tty font
-% only inside of @example and friends.
-\def\setkbdinputexample{\gdef\kbdexamplefont\ttsl}
-
\def\xkey{\key}
\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%
\ifx\one\xkey\ifx\threex\three \key{#2}%
@@ -1412,7 +1408,7 @@ where each line of input produces a line of output.}
% @uref (abbreviation for `urlref') takes an optional second argument
% specifying the text to display. First (mandatory) arg is the url.
% Perhaps eventually put in a hypertex \special here.
-%
+%
\def\uref#1{\urefxxx #1,,\finish}
\def\urefxxx#1,#2,#3\finish{%
\setbox0 = \hbox{\ignorespaces #2}%
@@ -2645,7 +2641,7 @@ width0pt\relax} \fi
\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
% Grab any single-column material above us.
\output = {\global\setbox\partialpage = \vbox{%
- %
+ %
% Here is a possibility not foreseen in manmac: if we accumulate a
% whole lot of material, we might end up calling this \output
% routine twice in a row (see the doublecol-lose test, which is
@@ -4402,15 +4398,15 @@ width0pt\relax} \fi
% Read the last existing aux file, if any. No error if none exists.
\def\readauxfile{\begingroup
\catcode`\^^@=\other
- \catcode`\^=\other
- \catcode`\^=\other
+ \catcode`\^^A=\other
+ \catcode`\^^B=\other
\catcode`\^^C=\other
\catcode`\^^D=\other
\catcode`\^^E=\other
\catcode`\^^F=\other
\catcode`\^^G=\other
\catcode`\^^H=\other
- \catcode`\^ =\other
+ \catcode`\^^K=\other
\catcode`\^^L=\other
\catcode`\^^N=\other
\catcode`\^^P=\other
@@ -4617,7 +4613,7 @@ width0pt\relax} \fi
% @image. We use the macros from epsf.tex to support this.
% If epsf.tex is not installed and @image is used, we complain.
-%
+%
% Check for and read epsf.tex up front. If we read it only at @image
% time, we might be inside a group, and then its definitions would get
% undone and the next image would fail.
diff --git a/manual/time.texi b/manual/time.texi
index d0b0e0a..1022e1a 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -885,11 +885,30 @@ A literal @samp{%} character.
The @var{size} parameter can be used to specify the maximum number of
characters to be stored in the array @var{s}, including the terminating
null character. If the formatted time requires more than @var{size}
-characters, the excess characters are discarded. The return value from
-@code{strftime} is the number of characters placed in the array @var{s},
-not including the terminating null character. If the value equals
-@var{size}, it means that the array @var{s} was too small; you should
-repeat the call, providing a bigger array.
+characters, @code{strftime} return zero and the content of the array
+@var{s} is indetermined. Otherwise the return value indicates the
+number of characters placed in the array @var{s}, not including the
+terminating null character.
+
+@emph{Warning:} This convention for the return value which is prescribed
+in @w{ISO C} can lead to problems in some situations. For certain
+format strings and certain locales the output really can be the empty
+string and this cannot be discovered by testing the return value only.
+E.g., in most locales the AM/PM time format is not supported (most of
+the world uses the 24 hour time representation). In such locales
+@code{"%p"} will return the empty string, i.e., the return value is
+zero. To detect situations like this something similar to the following
+code should be used:
+
+@smallexample
+buf[0] = '\1';
+len = strftime (buf, bufsize, format, tp);
+if (len == 0 && buf[0] != '\0')
+ @{
+ /* Something went wrong in the strftime call. */
+ @dots{}
+ @}
+@end smallexample
If @var{s} is a null pointer, @code{strftime} does not actually write
anything, but instead returns the number of characters it would have written.