Re: math_error.7 page for review

["Andries E. Brouwer" <Andries.Brouwer-rh8NL+sEX9E@public.gmane.org>]

On Mon, Jul 14, 2008 at 03:37:40PM +0200, Michael Kerrisk wrote:
> Hi Andries,

Hi Michael,

> > The includes <math.h>, <errno.h>, <fenv.h> are not mentioned.
> > The dependence on C99 is not mentioned.
> 
> Okay -- I added a SYNOPSIS section showing those headers.

Yes. Maybe also .br

> > I think math_errhandling can have the MATH_ERRNO bit set to indicate
> > that errors are signalled via errno, and it can have the MATH_ERREXCEPT
> > bit set to indicate that errors are signalled via floating-point exceptions,
> > but it can also be 0 and then neither errno nor fetestexcept are required
> > to give information.
> 
> AFAICS, at least one of the bits must be set in a conforming implementation.
> POSIX.1-2001 ... C99 Sec. 7.12 ...

OK.

> *** In the end, I'm still not certain whether *both* errno and
> fetestexcept() need to be checked to determine if an error occurred,
> or it if its sufficient to test either.

errno is the old-fashioned way, fetestexcept the modern way
One would have to audit the glibc source (in various versions)
but I would guess that in all recent cases fetestexcept suffices.

(Since you want to adapt all math fn man pages, you would probably
test current situation, and check libc source to see from when on we
have the current situation.)

> > The standard does not follow the SUSv3 math_err setup.
> 
> *** I do not understand this last sentence.  Did you omit/mistype some
> word here?  If not, can you say a little more?

Yes, sorry, I meant matherr, see matherr(3) on some suitable system.
Earlier one could have a system- or user-provided routine matherr()
that was invoked on error (with a struct describing the error).
The C standard people decided against that setup, but I think glibc
still supports it (on some architectures), probably with a suitable
#define _FOO_SOURCE.

Andries


       On   error,  many  mathematical  functions  (i.e.,  those  declared  in
       <math.h>) return a NaN (not a number).

On error, many of the mathematical functions declared in <math.h> ...

[you do not want to say that "declared in <math.h>" is a synonym for
"mathematical function"]

       However, in error cases where a
       NaN is not returned, the techniques described below are required.

Instead of looking at the return value (which is not always possible)
one can also check whether an error was signalled. There are two
signalling mechanisms: the older one sets \fIerrno\fP (to EDOM or ERANGE),
the newer one uses the floating point exception mechanism described in
fenv(3).

C99 and POSIX describe the math_errhandling identifier, that is supposed
to indicate which of these two mechanisms is in use (if ... then ...,
if ... then ...; possibly both). However, glibc does not make such an
identifier available. In practice glibc supports both.

For programs intended to be portable: ...(errno=0; feclearexcept; etc).


{very abbreviated suggested text fragment}

{again note: I did not do the audit}

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html