'\"!  eqn | mmdoc
'\"macro stdmacro
.if n .pH g3m.intro @(#)intro	40.8 of 10/10/89
.\" Copyright 1989 AT&T
.EQ
delim $$
gfont 1
gsize 8
.EN
.nr X
.if \nX=0 .ds x} intro 3M "Math Libraries" "\&"
.if \nX=1 .ds x} intro 3M "Math Libraries"
.if \nX=2 .ds x} intro 3M "" "\&"
.if \nX=3 .ds x} intro "" "" "\&"
.TH \*(x}
.SH NAME
\f4intro\f1 \- introduction to math libraries
.SH SYNOPSIS
\f4cc\f1
[\f2flag\fP \|.\|.\|.] \f2file\fP \|.\|.\|.
\f4\-lm\f1
[\f2library\fP \|.\|.\|.]
.PP
\f4cc \-O \-Ksd\f1
[\f2flag\fP \|.\|.\|.] \f2file\fP \|.\|.\|.
\f4\-J sfm\f1
[\f2library\fP \|.\|.\|.]
.PP
\f4#include <math.h>\f1
.SH DESCRIPTION
This section describes the functions
in the math libraries,
\f4libm\f1 and
\f4libsfm\f1\^.
Declarations for these functions may be obtained from
the
\f4#include\f1
file
\f4math.h\f1\^.
Several generally useful mathematical constants are also defined
there [see
\f4intro\fP(3)
and
\f4math\fP(5)].
.PP
The math libraries are not automatically loaded by the C 
compilation system;
use the \f4\-l\f1 or \f4\-J\f1
options to \f4cc\fP to access the libraries as follows:
.RS 8
.TP 10
\f4\-lm\f1
Search the regular math library, \f4libm\f1\^.
.TP
\f4\-J sfm\f1
Do in-line expansion of functions from the fast single-precision assembly
source math library, \f4libsfm\f1\^.
Specify \f4\-O \-Ksd\f1 to optimize for speed.
.RE
.TP 8
\f4libm\f1
Contains the full set of double-precision routines
plus some single-precision routines (designated by the suffix \f4f\f1)
that give better performance with less precision.
Selected routines are hand-optimized for performance.
The optimized routines include \f4sin\f1,
\f4cos\f1, \f4tan\f1, \f4atan\f1, \f4atan2\f1, \f4exp\f1, \f4log\f1, \f4log10\f1,
\f4pow\f1, and \f4sqrt\f1 and their single-precision equivalents.
.TP
\f4libsfm\f1
Contains the functions
\f4sinf\f1, \f4cosf\f1,
\f4tanf\f1, \f4asinf\f1, \f4acosf\f1, \f4atanf\f1,
\f4expf\f1, \f4logf\f1, \f4log10f\f1,
\f4powf\f1, and \f4sqrtf\f1.
The source library routines are in-line expanded by the
optimizer to provide faster execution by reducing the overhead of argument
passing, function calling and returning, and return value passing.
The source library is designed for applications that desire an increase
in speed at the potential cost of size.
.IP
\f4libsfm\f1 should be used only when necessary and with extreme caution.
It is a special purpose library that does not do
error checking or domain reduction. 
In other words, these functions never call \f4matherr\f1, and
arguments aren't reduced to be within a finite range.
.IP
Inputs to \f4sinf\f1 and \f4cosf\f1 must be in the range 
.P
.RS 16
$ -~pi over 2~\(<=~x~\(<=~pi over 2~$
.RE
.IP "" 8
Inputs to \f4tanf\f1 must be in the range
.P
.RS 16
$ -~pi over 2~<~x~<~pi over 2~$
.RE
.IP "" 8
Inputs to \f4sqrtf\f1, \f4logf\f1, and \f4log10f\f1 must be
greater than 0.
.SH DEFINITIONS
See \f4intro\fP(3) for C language definitions.
.SH FILES
.PD 0
.TP 24n
\f2LIBDIR\f1
usually \f4/usr/ccs/lib\fP
.TP
\f2LIBDIR\f4/libm.a\fP
.TP
\f2LIBDIR\f4/libsfm.sa\fP
.SH SEE ALSO
\f4cc\fP(1), \f4intro\fP(2),
\f4intro\fP(3), \f4math\fP(5).
.br
The ``Floating Point Operations'' chapter in the
\f2Programmer's Guide: ANSI C and Programming Support Tools\f1.
.SH DIAGNOSTICS
Error handling varies according to compilation mode.
Under the \f4\-Xt\f1 (default) option to \f4cc\f1,
these functions return
the conventional values
\f4\&0\f1, \f4\(+-HUGE\f1, or \f4NaN\f1
when the function is undefined for the
given arguments or when the value is not representable.
In the \f4\-Xa\f1 and \f4\-Xc\f1 compilation modes,
\f4\(+-HUGE_VAL\f1 is returned instead of \f4\(+-HUGE\f1.
(\f4HUGE_VAL\f1 and \f4HUGE\f1 are defined in \f4math.h\f1
to be infinity and the largest-magnitude single-precision number,
respectively.)
In every case, the external variable
\f4errno\f1 [see \f4intro\f1(2)]
is set to the value
\f4EDOM\fP
or
\f4ERANGE\fP,
although the value may vary for a given error
depending on compilation mode.
See the table under \f4matherr\f1(3M) below.
.\"	@(#)intro.3	6.3 of 10/20/83
.Ee
