The Math Libraries 
3

Some information can also be obtained from the man page Intro(3).
This chapter has the following organization:
The default directories for a standard installation of libm are:
The default directories for standard installtion of the header files for libm are: Table 31 lists the functions in libm with the names used for calling them from a C program.
Type 
Function Name 
^{1} On Solaris systems, this function is provided in the C library libc. 
Note that the functions gamma_r and lgamma_r are reentrant versions of gamma and lgamma.
The default directories for a standard installation of libsunmath are:
The default directories for standard installation of the header files for libsunmath are: Table 32 lists the functions in libsunmath; the names are those used for calling the double precision version of functions from a C program
The default directories for a standard installation of libmopt, libcopt, and libcx are:
The routines contained in libmopt replace corresponding routines in libm. The libmopt versions are generally noticeably faster. Note that unlike the libm versions, which can be configured to provide any of ANSI/POSIX, SVID, X/Open, or IEEEstyle treatment of exceptional cases, the libmopt routines only support IEEEstyle handling of these cases. (See Appendix F, "Standards Compliance.") To see which libm routines have counterparts in libmopt, use the nm command to search for all global symbols defined in libmopt.a.
SPARC and Power PC: On Solaris 2.x, libcx contains faster versions of the 128bit quadruple precision floating point arithmetic support routines. These routines are not intended to be called directly by the user; instead, they are called by the compiler. On Solaris 2.x, the Fortran 77 compiler links with libcx automatically unless the nocx
flag is used, but the C compiler does not automatically link with libcx. To use libcx with C programs, link with lcx
. (Note: A shared version of libcx, called libcx.so.1, is also provided. This version can be preloaded at run time by setting the environment variable LD_PRELOAD
to the full path name of the libcx.so.1 file.)
The default directory for a standard installation of libmvec is:
Table 33 lists the functions in libmvec. Note that only double precision versions of these functions are available.
Type 
Function Name 
See the libmvec(3m) manual page for more information.
Not all functions have q_... versions. Refer to math.h and sunmath.h for names and definitions of libm and libsunmath functions.
In FORTRAN programs, remember to declare r_... functions as real, d_... functions as double precision, and q_... functions as real*16. Otherwise, type mismatches may result.
Note  The Intel version of FORTRAN supports real and double precision only; it does not support REAL*16. The Intel version of C, however, supports long double.
Function 
Description 
Function 
Description 
remainder(x,y) is the operation specified in IEEE Standard 7541985. The difference between remainder(x,y) and fmod(x,y) is that the sign of the result returned by remainder(x,y) might not agree with the sign of either x or y, whereas fmod(x,y) always returns a result whose sign agrees with x. Both functions return exact results and do not generate inexact exceptions.
IEEE Function 
Single Precision 
Double Precision 
Quadruple Precision 
IEEE Function 
Single Precision 
Double Precision 
Quadruple Precision 
Note  You must declare d_function as double precision and q_function as REAL*16 in the FORTRAN program that uses them.
IEEE value 
Decimal value hexadecimal representation 
C, C++ FORTRAN 
IEEE value 
Decimal Value hexadecimal representation 
C, C++ FORTRAN 
IEEE value 
Decimal value hexadecimal representation 
C, C++ FORTRAN 
IEEE value 
Decimal value hexadecimal representation (80 bits) 
C, C++ 
IEEE Values: Double Extended Precision (Intel)
i = ieee_flags(action, mode, in, out);
The ASCII strings that are the possible values for the parameters are shown in Table 313:
Parameter 
C or C++ Type 
All Possible Values 
The ieee_flags(3m) man page describes the parameters in complete detail.
Some of the arithmetic features that can be modified by using ieee_flags are covered in the following paragraphs. Chapter 4 contains more information on ieee_flags and IEEE exception flags.
When mode is ``direction'', the specified action applies to the current rounding direction. The possible rounding directions are: round towards nearest, round towards zero, round towards + or round towards . The IEEE default rounding direction is round towards nearest. This means that when the mathematical result of an operation lies halfway between two representable numbers, the one nearest to the mathematical result is delivered as the result. If the mathematical result lies halfway between the two representable numbers, then round to nearest mode specifies round to the nearest even number (final bit is zero.)
Rounding towards zero is the way many preIEEE computers work, and corresponds mathematically to truncating the result. For example, if 2/3 is rounded to 6 decimal digits, the result is .666667 when the rounding mode is round towards nearest, but .666666 when the rounding mode is round towards zero.
When using ieee_flags to examine, clear, or set the rounding direction, possible values for the four input parameters
Parameter 
Possible value (mode is direction) 
Rounding precision cannot be set on systems using SPARC or PowerPC processors. On these systems, calling ieee_flags with mode = ``precision'' has no effect on computation.
Finally, when mode is ``exception'', the specified action applies to the current IEEE exception flags. See Chapter 4, "Exceptions and Exception Handling", for more information about using ieee_flags to examine and control the IEEE exception flags.
ieee_retrospective prints information about exception flags that are raised, and exceptions for which a trap is enabled. These two distinct, if related, pieces of information should not be confused. If an exception flag is raised, then that exception occurred at some point during program execution. If a trap is enabled for an exception, then the exception may not have actually occurred (but if it had, a SIGFPE signal would have been delivered). The ieee_retrospective message is meant to alert you about exceptions that may need to be investigated (if the exception flag is raised), or to remind you that exceptions may have been handled by a signal handler (if the exception's trap is enabled.) Chapter 4, "Exceptions and Exception Handling," discusses exceptions, signals, and traps, and shows how to investigate the cause of a raised exception.
The syntax for calling this function is:
The following example shows four of the six ieee_retrospective
warning messages:
A warning message appears only if trapping is enabled or an exception was raised.
You can suppress ieee_retrospective messages from FORTRAN programs
by one of three methods. One approach is to clear all outstanding exceptions,
disable traps, and restore roundtonearest, extended precision, and standard
modes before the program exits. To do this, call ieee_flags,
ieee_handler, and standard_arithmetic as follows:
character*8 out i = ieee_flags('clearall', '', '', out) call ieee_handler('clear', 'all', 0) call standard_arithmetic() 
Another way to avoid seeing ieee_retrospective messages is simply to redirect stderr to a file. Of course, this method should not be used if the program sends output other than ieee_retrospective messages to stderr.
Note  Clearing outstanding exceptions without investigating their cause is not recommended.
The third approach is to include a dummy ieee_retrospective function in the program, for example:
subroutine ieee_retrospective return end 
The function nonstandard_arithmetic causes underflowed results to be flushed to zero on those SPARC implementations that have a mode in hardware in which flushing to zero is faster. The tradeoff for speed is accuracy, because the benefits of gradual underflow are lost.
The function standard_arithmetic resets the hardware to use the default IEEE arithmetic. Both functions have no effect on implementations that provide only the default IEEE 754 style of arithmeticSuperSPARC is such an implementation.
Both the tabledriven and polynomial/rational approximation algorithms for the common elementary functions in libm and the common single precision elementary functions in libsunmath deliver results that are accurate to within one unit in the last place (ulp). On SPARC and PowerPC, the common quadruple precision elementary functions in libsunmath deliver results that are accurate to within one ulp, except for the expm1l and log1pl functions, which deliver results accurate to within two ulps. These error bounds have been obtained by direct analysis of the algorithms. Users may also test the accuracy of these routines using BeEF, the Berkeley Elementary Function test programs, developed by Z. Alex Liu and available from netlib in the ucbtest package.
Because is not a machinerepresentable number, it must be approximated. The error in the final computed trigonometric function depends on the rounding errors in argument reduction (with an approximate as well as the rounding), and approximation errors in computing the trigonometric function of the reduced argument. Even for fairly small arguments, the relative error in the final result may be dominated by the argument reduction error, while even for fairly large arguments, the error due to argument reduction may be no worse than the other errors.
There is widespread misapprehension that trigonometric functions of all large arguments are inherently inaccurate, and all small arguments relatively accurate. This is based on the simple observation that large enough machinerepresentable numbers are separated by a distance greater than .
There is no inherent boundary at which computed trigonometric function values suddenly become bad, nor are the inaccurate function values useless. Provided that the argument reduction is done consistently, the fact that the argument reduction is performed with an approximation to is practically undetectable, because all essential identities and relationships are as well preserved for large arguments as for small.
libm and libsunmath trigonometric functions use an "infinitely" precise for argument reduction. The value 2/ is computed to 916 hexadecimal digits and stored in a lookup table to use during argument reduction.
The group of functions sinpi, cospi, tanpi (see Table 32 on page 34), scales the input argument by to avoid inaccuracies introduced by range reduction.
Formats supported include those used by SPARC (IEEE), IBM PC, VAX®, IBM S/370, and Cray®.
Refer to the man page on convert_external(3m) for an example of taking data generated on a Cray, and using the function convert_external to convert the data into the IEEE format expected on SPARC systems.
In addition, shufrans(3m) shuffles a set of pseudorandom numbers to provide even more randomness for applications that need it.
The functions in addrans (3m) are generally more efficient but their theory is not as refined as those in lcrans (3m). Refer to the article "Random Number Generators: Good Ones Are Hard To Find", by S. Park and K. Miller, Communications of the ACM, October 1988, for a discussion of the theoretical properties of these algorithms. Additive random number generators are discussed in Volume 2 of Knuth's The Art of Computer Programming.
The random number generators are available in four versions, for the four data types: signed integer, unsigned integer, single precision floatingpoint, and double precision floatingpoint. These functions can be used in two ways: to generate random numbers one at a time (one per function call), or to generate arrays of random numbers (one array per function call.)
When using addrans and lcrans to provide variates one at a time, they are constrained to the intervals shown in Table 315.
Type 
Lower Bound 
Upper Bound 
Value 
Value  
However, if addrans or lcrans are used to generate arrays of data, the upper and lower bounds of the interval over which the data is uniformly distributed can be controlled.
Appendix A, "Examples," on page 91, shows an example that uses addrans to generate an array of 1000 random numbers, uniformly distributed over the interval, [0, 3.7e9].
Base conversion is not too difficult for integer formats but gets more complicated when floating point is involved; as with other floatingpoint operations, rounding errors occur.
For instance, on conversion from internal floating point to an external decimal representation, the mathematical problem to be solved in default rounding mode is as follows:
In the case of printf %f or FORTRAN F format with n digits after the decimal point:
In the case of printf %e or FORTRAN E format with n significant digits: and
Correct rounding is required by the IEEE Standard 754. The standard requires correct rounding for typical numbers whose magnitudes range from 10^{ 44} to 10^{+44}, but permits slightly incorrect rounding for larger exponentsthe Sun tabledriven algorithm for rounding is accurate through the entire range. (See section 5.6 of IEEE Standard 754.)
See Appendix G, "References," on page 237, for references on base conversion. Particularly good references are Coonen's thesis and Sterbenz's book.