libm

Syntax

#include <libm/math.h>

enum fdversion {fdlibm_ieee = -1, fdlibm_svid, fdlibm_xopen, fdlibm_posix};

#define _LIB_VERSION_TYPE enum fdversion
#define _LIB_VERSION _fdlib_version  

extern  _LIB_VERSION_TYPE  _LIB_VERSION;

#define _IEEE_  fdlibm_ieee
#define _SVID_  fdlibm_svid
#define _XOPEN_ fdlibm_xopen
#define _POSIX_ fdlibm_posix

_LIB_VERSION_TYPE _LIB_VERSION = _IEEE_;

Description

The alternate math library, `libm.a', provides more accurate versions of mathematical functions than those included in the default `libc.a' library. It also allows to create programs with well-defined and standard-compliant behavior when numerical errors occur. In contrast, the functions in the default `libc.a' will not set errno in such cases, and will not call matherr.

To use the alternate math library with your program, you need to do the following:

• Include the header <libm/math.h>. Alternatively, you can include <math.h> as usual and compile with `-D_USE_LIBM_MATH_H' option to gcc, which will cause it to use `libm/math.h' instead of the default `math.h'. (The second possibility leaves the source ANSI-compliant.)
• Set the global variable _fdlib_version to a value other than the default _IEEE_. The possible values are listed and explained below.
• At the beginning of your main function, set the FPU to a predictable state by calling _clear87 (see section _clear87) and _fpreset (see section _fpreset) library functions. (Another possibility is to make these calls in a function declared with __attribute__((constructor)), so it will be called before main.)
• Link your program with the `libm.a' library, e.g. by specifying `-lm' on the link command line.

The functions in `libm.a' can emulate different standards. You can select to which standard your program will comply by setting the global variable _fdlib_version (or the macro _LIB_VERSION which evaluates to it) to one of the values below. This will only effect the behavior of the math functions when an error is signalled by the FPU.

_IEEE_

The default value, specifies IEEE-compliant operation. In case of an error, this version will immediately return whatever result is computed by the FPU, and will not set errno. This gives the fastest code.

_POSIX_

In case of an error, this version will set errno to the appropriate value (EDOM or ERANGE) and return to the caller, without calling the matherr function (see section matherr). This version should be used for maximum POSIX- and ANSI-compliance.

_SVID_

This version is compliant with the System V Interface Definition. This is the slowest version. In case of an error, it calls the matherr function (see section matherr), which can be customized to the specific application needs. If matherr returns zero, a message is printed to the standard error stream which states the name of the function that generated the error and the error type, and errno is set. If matherr returns non-zero, there will be no message and errno will be left unaltered.

_XOPEN_

Complies to the X/Open specifications. It behaves exactly like _SVID_, but it never prints an error message, even if matherr returns zero.

Portability

not ANSI, not POSIX

Example

/*  Testing errno == EDOM after sqrt(-1).

    !!!  MUST compile with -lm  !!!  */

#include <assert.h>
#include <errno.h>
#include <stdio.h>
#include <libm/math.h>	/* or #define _USE_LIBM_MATH_H and #include <math.h> */
#include <float.h>

/* Setting _LIB_VERSION to anything but _IEEE_ will turn on errno handling. */
_LIB_VERSION_TYPE _LIB_VERSION = _POSIX_;

int main (void)
{
  /* Reset the FPU (possible previous FP problems).  */
  _clear87 ();
  _fpreset ();

  /* Run the test.  */
  errno = 0;
  assert(errno == 0);
  sqrt(-1.0);
  assert(errno == EDOM); /* this line should NOT cause the assertion to fail */

  return(0);
}

Go to the first, previous, next, last section, table of contents.