diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/arith.texi | 16 | ||||
| -rw-r--r-- | manual/errno.texi | 2 | ||||
| -rw-r--r-- | manual/libc.texinfo | 2 | ||||
| -rw-r--r-- | manual/math.texi | 757 | ||||
| -rw-r--r-- | manual/pattern.texi | 3 | ||||
| -rw-r--r-- | manual/socket.texi | 38 | ||||
| -rw-r--r-- | manual/texinfo.tex | 22 | ||||
| -rw-r--r-- | manual/time.texi | 29 |
8 files changed, 809 insertions, 60 deletions
diff --git a/manual/arith.texi b/manual/arith.texi index 1268e37e31..7f8c205ebb 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 800b0393c5..c073deb7f8 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 2d79d960af..cb1769fec7 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 e2adccddb3..d4449bb24d 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 020a40e7da..1decfe3dae 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 cc39bec452..0353eb7ed3 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 813d3c2bb7..35bc0b0c72 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 d0b0e0a111..1022e1a41f 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. |