glibc/manual/math.texi
Ulrich Drepper 2c6fe0bd3b update from main archive 961105
Wed Nov  6 04:30:26 1996  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/unix/sysv/linux/syscalls.list: Add weak alias llseek for
	_llseek syscall.  Reported by Andy Sewell <puck@pookhill.demon.co.uk>.

	* string/argz.h: Don't protect by __USE_GNU.

Tue Nov  5 23:38:28 1996  Ulrich Drepper  <drepper@cygnus.com>

	* Lots of files: Update and reformat copyright.

	* Makefile (headers): Add xopen_lim.h.

	* catgets/nl_types.h: Move __BEGIN_DECLS before definition of nl_catd.

	* grp/grp.h: Define setgrent, getgrent, endgrent, and getgrent_r
	if __USE_XOPEN_EXTENDED is defined.
	* pwd/pwd.h: Define setpwent, getpwent, endpwent, and getpwent_r
	if __USE_XOPEN_EXTENDED is defined.

	* io/Makefile (routines): Add lchown.

	* io/sys/poll.h: Add definition of POLLWRNORM.

	* io/sys/stat.h: Declare lstat, fchmod, mknod when
	__USE_XOPEN_EXTENDED is defined.

	* libio/Makefile (routines): Add obprintf.
	* libio/obprintf.c: New file.
	* libio/iolibio.h: Add prototypes for _IO_obstack_vprintf and
	_IO_obstack_printf.
	* libio/libio.h: Fix typo.
	* libio/stdio.h: Declare tempnam if __USE_XOPEN_EXTENDED is defined.
	Add prototypes for obstack_vprintf and obstack_printf.

	* manual/creature.texi: Describe _XOPEN_SOURCE macro.
	* manual/intro.texi: Add reference to NSS chapter.
	* manual/libc.texinfo: Update UPDATED.
	Comment out `@printindex cp'.  It works again.
	* manual/memory.texi: Add description for obstack_ptr_grow,
	obstack_int_grow, obstack_ptr_grow_fast, and obstack_int_grow_fast.
	* manual/nss.texi: Add a few @cindex entries and change NSS_STATUS_*
	index entries to @vindex.
	* manual/users.texi: Correct @cindex entry for Netgroup.

	* math/mathcalls.h: Use __USE_XOPEN and __USE_XOPEN_EXTENDED to
	make declarations visible for X/Open sources.

	* misc/search.h: Declare insque/remque only is __USE_SVID or
	__USE_XOPEN_EXTENDED is defined.

	* misc/sys/uio.h (readv, writev): Change return value from int to
	ssize_t.

	* posix/Makefile (headers): Add re_comp.h.
	* posix/re_comp.h: New file.  XPG interface to regex functions.

	* posix/getconf.c: Add all names from XPG4.2.
	* posix/posix1_lim.h: Increase minimum values for _POSIX_CHILD_MAX
	and _POSIX_OPEN_MAX to minimums from XPG4.2.
	* sysdeps/generic/confname.h: Add all _SC_* names from XPG4.2.
	* sysdeps/posix/sysconf.c: Handle new _SC_* values.
	* sysdeps/stub/sysconf.c: Likewise.

	* posix/unistd.h: Add declaration of ualarm and lchown.  Declare
	usleep, fchown, fchdir, nice, getpgid, setsid, getsid, setreuid,
	setregid, vfork, ttyslot, symlink, readlink, gethostid, truncate,
	ftruncate, getdtablesize, brk, sbrk, lockf when
	__USE_XOPEN_EXTENDED is defined.

	* posix/sys/wait.h: Declare wait3 if __USE_XOPEN_EXTENDED is defined.

	* shadow/shadow.h: Define SHADOW using _PATH_SHADOW.
	* sysdeps/generic/paths.h: Define _PATH_SHADOW.
	* sysdeps/unix/sysv/linux/paths.h: Likewise.

	* signal/signal.h: Declare killpg, sigstack and sigaltstack when
	__USE_XOPEN_EXTENDED is defined.

	* stdio/stdio.h: Declare tempnam when __USE_XOPEN is defined.

	* stdlib/stdlib.h: Make rand48 functions available when __USE_XOPEN
	is defined.
	Likewise for valloc, putenv, realpath, [efg]cvt*, and getsubopt
	functions.

	* string/string.h: Make memccpy, strdup, bcmp, bcopy, bzero, index,
	and rindex available when __USE_XOPEN_EXTENDED is defined.

	* sysdeps/mach/getpagesize.c: De-ANSI-fy.  Change return type to int.
	* sysdeps/posix/getpagesize.c: Likewise.
	* sysdeps/stub/getpagesize.c: Likewise.
	* sysdeps/unix/getpagesize.c: Likewise.

	* time/africa: Update from tzdata1996l.
	* time/asia: Likewise.
	* time/australia: Likewise.
	* time/europe: Likewise.
	* time/northamerica: Likewise.
	* time/pacificnew: Likewise.
	* time/southamerica: Likewise.
	* time/tzfile.h: Update from tzcode1996m.

	* time/time.h: Declare strptime if __USE_XOPEN.
	Declare daylight and timezone also if __USE_XOPEN.

	* time/sys/time.h: Remove declaration of ualarm.

	* wctype/wctype.h: Just reference ISO C standard.

Tue Nov  5 01:26:32 1996  Richard Henderson  <rth@tamu.edu>

	* crypt/Makefile: Add crypt routines to libc as well iff
	$(crypt-in-libc) is set.  Do this for temporary binary compatibility
	on existing Linux/Alpha installations.

	* stdlib/div.c, sysdeps/generic/div.c: Move file to .../generic/.
	* stdlib/ldiv.c, sysdeps/generic/ldiv.c: Likewise.
	* stdlib/lldiv.c, sysdeps/generic/lldiv.c: Likewise.
	* sysdeps/alpha/Makefile (divrem): Add divlu, dviqu, remlu, and
	remqu.
	* sysdeps/alpha/div.S: New file.
	* sysdeps/alpha/ldiv.S: New file.
	* sysdeps/alpha/lldiv.S: New file.
	* sysdeps/alpha/divrem.h: Merge signed and unsigned division.
	Take pointers from Linus and tighten the inner loops a bit.
	* sysdeps/alpha/divl.S: Change defines for merged routines.
	* sysdeps/alpha/divq.S: Likewise.
	* sysdeps/alpha/reml.S: Likewise.
	* sysdeps/alpha/remq.S: Likewise.
	* sysdeps/alpha/divlu.S: Remove file.
	* sysdeps/alpha/divqu.S: Likewise.
	* sysdeps/alpha/remlu.S: Likewise.
	* sysdeps/alpha/remqu.S: Likewise.

	* sysdeps/alpha/bsd-_setjmp.S: If PROF, call _mcount.
	* sysdeps/alpha/bsd-setjmp.S: Likewise.
	* sysdeps/alpha/bzero.S: Likewise.
	* sysdeps/alpha/ffs.S: Likewise.
	* sysdeps/alpha/htonl.S: Likewise.
	* sysdeps/alpha/htons.S: Likewise.
	* sysdeps/alpha/memchr.S: Likewise.
	* sysdeps/alpha/memset.S: Likewise.
	* sysdeps/alpha/s_copysign.S: Likewise.
	* sysdeps/alpha/s_fabs.S: Likewise.
	* sysdeps/alpha/setjmp.S: Likewise.
	* sysdeps/alpha/stpcpy.S: Likewise.
	* sysdeps/alpha/stpncpy.S: Likewise.
	* sysdeps/alpha/strcat.S: Likewise.
	* sysdeps/alpha/strchr.S: Likewise.
	* sysdeps/alpha/strcpy.S: Likewise.
	* sysdeps/alpha/strlen.S: Likewise.
	* sysdeps/alpha/strncat.S: Likewise.
	* sysdeps/alpha/strncpy.S: Likewise.
	* sysdeps/alpha/strrchr.S: Likewise.
	* sysdeps/alpha/udiv_qrnnd.S: Likewise.  Fix private labels.
	Convert two small jumps to use conditional moves.
	* sysdeps/unix/alpha/sysdep.h: Compress all __STDC__ nastiness.
	(PSEUDO): If PROF, call _mcount.
	* sysdeps/unix/sysv/linux/alpha/brk.S: If PROF, call _mcount.
	* sysdeps/unix/sysv/linux/alpha/clone.S: Likewise.
	* sysdeps/unix/sysv/linux/alpha/ieee_get_fp_control.S: Likewise.
	* sysdeps/unix/sysv/linux/alpha/ieee_set_fp_control.S: Likewise.
	* sysdeps/unix/sysv/linux/alpha/llseek.S: Likewise.
	* sysdeps/unix/sysv/linux/alpha/sigsuspend.S: Likewise.
	* sysdeps/unix/sysv/linux/alpha/syscall.S: Likewise.

	* sysdeps/alpha/memcpy.S: New file.  Odd layout because it should
	eventually contain memmove as well.
	* sysdeps/alpha/strcmp.S: New file.
	* sysdeps/alpha/strncmp.S: New file.
	* sysdeps/alpha/w_sqrt.S: New file.

Tue Nov  5 18:06:06 1996  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/mach/hurd/ttyname_r.c: Use `size_t' for len variable.

Tue Nov  5 12:09:29 1996  Ulrich Drepper  <drepper@cygnus.com>

	* sysdep/generic/sysdep.h: Define END only if not yet defined.
	* sysdep/unix/sysdep.h: Define PSEUDO_END only if not yet defined.
	Reported by Thomas Bushnell, n/BSG.

Mon Nov  4 22:46:53 1996  Ulrich Drepper  <drepper@cygnus.com>

	* manual/users.texi (Netgroup Data): Remove { } around @cindex.

Mon Nov  4 19:07:05 1996  Ulrich Drepper  <drepper@cygnus.com>

	* malloc/calloc.c: Check for overflow before trying to allocate
	memory.  Proposed by Neil Matthews <nm@adv.sbc.sony.co.jp>.

Fri Nov  1 18:18:32 1996  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* manual/llio.texi (Operating Modes): Add missing arguments to
	@deftypevr in O_NONBLOCK description.

	* manual/time.texi (Time Zone Functions): Enclose type name in
	braces in description of tzname.  FIXME: this does not yet work
	correctly in info.

Sun Nov  3 17:29:06 1996  Ulrich Drepper  <drepper@cygnus.com>

	* features.h: Add X/Open macros.
	* posix/unistd.h: Define X/Open macros.
	* sysdeps/generic/confname.h: Add _SC_XOPEN_XCU_VERSION,
	_SC_XOPEN_UNIX, _SC_XOPEN_CRYPT, _SC_XOPEN_ENH_I18N,
	_SC_XOPEN_SHM, _SC_2_CHAR_TERM, _SC_2_C_VERSION, and _SC_2_UPE.
	* sysdeps/posix/sysconf.c: Handle new constants.
	* sysdeps/stub/sysconf.c: Likewise.
	* sysdeps/unix/sysv/linux/posix_opt.h: Add definition of _XOPEN_SHM.

	* catgets/catgets.c (catopen): Set errno to ENOMEM when
	we run out of memory.
	(catgets): Set errno to EBADF when catalog handle is invalid.
	Set errno to ENOMSG when translation is not available.
	(catclose): Set errno to EBADF when catalog handle is invalid.

	* ctype/ctype.h: Declare isascii and toascii when __USE_XOPEN.
	Likewise for _toupper and _tolower.

	* manual/arith.texi: Document strtoq, strtoll, strtouq, strtoull,
	strtof, and strtold.
	* manual/math.texi: Document HUGE_VALf and HUGE_VALl.
	* manual/stdio.h: Document ' flag for numeric formats of scanf.
	* manual/users.texi: Document that cuserid shouldn't be used.

	* misc/Makefile (routines): Add dirname.
	(headers): Add libgen.h.
	(tests): Add tst-dirname.
	* misc/dirname.c: New file.
	* misc/libgen.h: New file.
	* misc/tst-dirname.c: New file.

	* misc/search.h: Parameter of hcreate must be of type size_t.
	* misc/hsearch.c: Likewise.
	* misc/hsearch_r.c: Likewise for hcreate_r.
	* misc/search.h: Parameters of insque and remque must be `void *'.
	* misc/insremque.c: Likewise.

	* posix/unistd.h: Move declarations of mktemp and mkstemp to...
	* stdlib/stdlib.h: ...here.
	* posix/unistd.h [__USE_XOPEN]: Add prototypes for crypt, setkey,
	encrypt, and swab.

	* stdio-common/printf-parse.h (struct printf_spec): Add pa_wchar
	and pa_wstring.
	(parse_one_spec): Remove Linux compatibility code.
	Recognize %C and %S formats.
	* stdio-common/printf.h: Add PA_WCHAR and PA_WSTRING.
	* stdio-common/vfprintf.c: Add implementation of %C and %S format.
	* stdio-common/vfscanf.c: Likewise for scanf.

	* stdlib/l64a.c: Return value for 0 must be the empty string.
	* stdlib/stdlib.h: Declare reentrant function from rand49 family
	only if __USE_REENTRANT.
	Declare rand48 functions also if __USE_XOPEN.

	* stdlib/strtol.c: Return 0 and set errno to EINVAL when BASE is
	not a legal value.
	Return 0 and set errno to EINVAL when strou* sees negativ number.
	* stdlib/tst-strtol.c: De-ANSI-fy.
	Change expected results for test of unsigned function and negative
	input.

	* string/stratcliff.c: Prevent warnings.
	* string.h: Move declaration of swab to <unistd.h>.
	* string/swab.c: De-ANSI-fy.

	* sysdeps/posix/cuserid.c: Implement using getpwuid_r.
	* sysdeps/posix/mkstemp.c: Include <stdlib.h> for prototype.
	* sysdeps/posix/mktemp.c: Likewise.
	* sysdeps/stub/mkstemp.c: Likewise.
	* sysdeps/stub/mktemp.c: Likewise.

	* sysvipc/sys/ipc.h: Prototypes of ftok have to be of types `const
 	char *' and `int'.
	* sysvipc/ftok.c: Likewise.  Make sure only lower 8 bits of
 	PROJ_ID are used.

Sun Nov  3 03:21:28 1996  Heiko Schroeder  <Heiko.Schroeder@post.rwth-aachen.de>

	* locale/programs/ld-numeric.c (numeric_output): Compute idx[0]
	correctly.

Sat Nov  2 17:44:32 1996  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/posix/cuserid.c: Use reentrant functions.
	* manual/users.texi: Tell that cuserid is marked to be withdrawn in
	XPG4.2.

Sat Nov  2 14:26:37 1996  Ulrich Drepper  <drepper@cygnus.com>

	Linus said he will make sure no system call will return a value
	in -1 ... -4095 as a valid result.
	* sysdeps/unix/sysv/linux/i386/sysdep.h: Correct test for error.
	* sysdeps/unix/sysv/linux/i386/syscall.S: Likewise.
	* sysdeps/unix/sysv/linux/m68k/sysdep.h: Likewise.
	* sysdeps/unix/sysv/linux/m68k/syscall.S: Likewise.

Sat Nov  2 16:54:49 1996  NIIBE Yutaka  <gniibe@mri.co.jp>

	* sysdeps/stub/lockfile.c [!USE_IN_LIBIO]: Define weak alias for
	__funlockfile, not a circular alias.
	Define __IO_ftrylockfile if USE_IN_LIBIO and __ftrylockfile if not,
	not vice versa.

	* sysdeps/unix/sysv/linux/i386/sysdep.S (__errno_location): Make
	it a weak symbol.
	* sysdeps/unix/sysv/linux/m68k/sysdep.S (__errno_location): Likewise.


	Likewise.

	* crypt/Makefile (rpath-link): Extend search path to current directory.
1996-11-06 04:24:40 +00:00

529 lines
19 KiB
Plaintext

@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
@chapter Mathematics
This chapter contains information about functions for performing
mathematical computations, such as trigonometric functions. Most of
these functions have prototypes declared in the header file
@file{math.h}.
@pindex math.h
All of the functions that operate on floating-point numbers accept
arguments and return results of type @code{double}. In the future,
there may be additional functions that operate on @code{float} and
@code{long double} values. For example, @code{cosf} and @code{cosl}
would be versions of the @code{cos} function that operate on
@code{float} and @code{long double} arguments, respectively. In the
meantime, you should avoid using these names yourself. @xref{Reserved
Names}.
@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.
@end menu
@node Domain and Range Errors
@section Domain and Range Errors
@cindex domain error
Many of the functions listed in this chapter are defined mathematically
over a domain that is only a subset of real numbers. For example, the
@code{acos} function is defined over the domain between @code{-1} and
@code{1}. If you pass an argument to one of these functions that is
outside the domain over which it is defined, the function sets
@code{errno} to @code{EDOM} to indicate a @dfn{domain error}. On
machines that support @w{IEEE 754} floating point, functions reporting
error @code{EDOM} also return a NaN.
Some of these functions are defined mathematically to result in a
complex value over parts of their domains. The most familiar example of
this is taking the square root of a negative number. The functions in
this chapter take only real arguments and return only real values;
therefore, if the value ought to be nonreal, this is treated as a domain
error.
@cindex range error
A related problem is that the mathematical result of a function may not
be representable as a floating point number. If magnitude of the
correct result is too large to be represented, the function sets
@code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
returns a particular very large value (named by the macro
@code{HUGE_VAL}) or its negation (@w{@code{- HUGE_VAL}}).
If the magnitude of the result is too small, a value of zero is returned
instead. In this case, @code{errno} might or might not be
set to @code{ERANGE}.
The only completely reliable way to check for domain and range errors is
to set @code{errno} to @code{0} before you call the mathematical function
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.)
@comment math.h
@comment ANSI
@deftypevr Macro double HUGE_VAL
An expression representing a particular very large number. On machines
that use @w{IEEE 754} floating point format, the value is ``infinity''.
On other machines, it's typically the largest positive number that can
be represented.
The value of this macro is used as the return value from various
mathematical @code{double} returning functions in overflow situations.
@end deftypevr
@comment math.h
@comment GNU
@deftypevr Macro float HUGE_VALf
This macro is similar to the @code{HUGE_VAL} macro except that it is
used by functions returning @code{float} values.
This macro is a GNU extension.
@end deftypevr
@comment math.h
@comment GNU
@deftypevr Macro {long double} HUGE_VALl
This macro is similar to the @code{HUGE_VAL} macro except that it is
used by functions returning @code{long double} values. The value is
only different from @code{HUGE_VAL} if the architecture really supports
@code{long double} values.
This macro is a GNU extension.
@end deftypevr
@comment
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 Trig Functions
@section Trigonometric Functions
@cindex trigonometric functions
These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
The arguments to all of these functions are in units of radians; recall
that pi radians equals 180 degrees.
@cindex pi (trigonometric constant)
The math library doesn't define a symbolic constant for pi, but you can
define your own if you need one:
@smallexample
#define PI 3.14159265358979323846264338327
@end smallexample
@noindent
You can also compute the value of pi with the expression @code{acos
(-1.0)}.
@comment math.h
@comment ANSI
@deftypefun double sin (double @var{x})
This function returns the sine of @var{x}, where @var{x} is given in
radians. The return value is in the range @code{-1} to @code{1}.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double cos (double @var{x})
This function returns the cosine of @var{x}, where @var{x} is given in
radians. The return value is in the range @code{-1} to @code{1}.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double tan (double @var{x})
This function returns the tangent of @var{x}, where @var{x} is given in
radians.
The following @code{errno} error conditions are defined for this function:
@table @code
@item ERANGE
Mathematically, the tangent function has singularities at odd multiples
of pi/2. If the argument @var{x} is too close to one of these
singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
either positive or negative @code{HUGE_VAL}.
@end table
@end deftypefun
@node Inverse Trig Functions
@section Inverse Trigonometric Functions
@cindex inverse trigonmetric functions
These are the usual arc sine, arc cosine and arc tangent functions,
which are the inverses of the sine, cosine and tangent functions,
respectively.
@comment math.h
@comment ANSI
@deftypefun double asin (double @var{x})
This function computes the arc sine of @var{x}---that is, the value whose
sine is @var{x}. The value is in units of radians. Mathematically,
there are infinitely many such values; the one actually returned is the
one between @code{-pi/2} and @code{pi/2} (inclusive).
@code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
out of range. The arc sine function is defined mathematically only
over the domain @code{-1} to @code{1}.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double acos (double @var{x})
This function computes the arc cosine of @var{x}---that is, the value
whose cosine is @var{x}. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between @code{0} and @code{pi} (inclusive).
@code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
out of range. The arc cosine function is defined mathematically only
over the domain @code{-1} to @code{1}.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double atan (double @var{x})
This function computes the arc tangent of @var{x}---that is, the value
whose tangent is @var{x}. The value is in units of radians.
Mathematically, there are infinitely many such values; the one actually
returned is the one between @code{-pi/2} and @code{pi/2}
(inclusive).
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double atan2 (double @var{y}, double @var{x})
This is the two argument arc tangent function. It is similar to computing
the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
are used to determine the quadrant of the result, and @var{x} is
permitted to be zero. The return value is given in radians and is in
the range @code{-pi} to @code{pi}, inclusive.
If @var{x} and @var{y} are coordinates of a point in the plane,
@code{atan2} returns the signed angle between the line from the origin
to that point and the x-axis. Thus, @code{atan2} is useful for
converting Cartesian coordinates to polar coordinates. (To compute the
radial coordinate, use @code{hypot}; see @ref{Exponents and
Logarithms}.)
The function @code{atan2} sets @code{errno} to @code{EDOM} if both
@var{x} and @var{y} are zero; the return value is not defined in this
case.
@end deftypefun
@node Exponents and Logarithms
@section Exponentiation and Logarithms
@cindex exponentiation functions
@cindex power functions
@cindex logarithm functions
@comment math.h
@comment ANSI
@deftypefun double exp (double @var{x})
The @code{exp} function returns the value of e (the base of natural
logarithms) raised to power @var{x}.
The function fails, and sets @code{errno} to @code{ERANGE}, if the
magnitude of the result is too large to be representable.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double log (double @var{x})
This function returns the natural logarithm of @var{x}. @code{exp (log
(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
C.
The following @code{errno} error conditions are defined for this function:
@table @code
@item EDOM
The argument @var{x} is negative. The log function is defined
mathematically to return a real result only on positive arguments.
@item ERANGE
The argument is zero. The log of zero is not defined.
@end table
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double log10 (double @var{x})
This function returns the base-10 logarithm of @var{x}. Except for the
different base, it is similar to the @code{log} function. In fact,
@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double pow (double @var{base}, double @var{power})
This is a general exponentiation function, returning @var{base} raised
to @var{power}.
@need 250
The following @code{errno} error conditions are defined for this function:
@table @code
@item EDOM
The argument @var{base} is negative and @var{power} is not an integral
value. Mathematically, the result would be a complex number in this case.
@item ERANGE
An underflow or overflow condition was detected in the result.
@end table
@end deftypefun
@cindex square root function
@comment math.h
@comment ANSI
@deftypefun double sqrt (double @var{x})
This function returns the nonnegative square root of @var{x}.
The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
@var{x} is negative. Mathematically, the square root would be a complex
number.
@end deftypefun
@cindex cube root function
@comment math.h
@comment BSD
@deftypefun double cbrt (double @var{x})
This function returns the cube root of @var{x}. This function cannot
fail; every representable real value has a representable real cube root.
@end deftypefun
@comment math.h
@comment BSD
@deftypefun double hypot (double @var{x}, double @var{y})
The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
@var{y}*@var{y})}. (This is the length of the hypotenuse of a right
triangle with sides of length @var{x} and @var{y}, or the distance
of the point (@var{x}, @var{y}) from the origin.) See also the function
@code{cabs} in @ref{Absolute Value}.
@end deftypefun
@comment math.h
@comment BSD
@deftypefun double expm1 (double @var{x})
This function returns a value equivalent to @code{exp (@var{x}) - 1}.
It is computed in a way that is accurate even if the value of @var{x} is
near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
to subtraction of two numbers that are nearly equal.
@end deftypefun
@comment math.h
@comment BSD
@deftypefun double log1p (double @var{x})
This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
It is computed in a way that is accurate even if the value of @var{x} is
near zero.
@end deftypefun
@node Hyperbolic Functions
@section Hyperbolic Functions
@cindex hyperbolic functions
The functions in this section are related to the exponential functions;
see @ref{Exponents and Logarithms}.
@comment math.h
@comment ANSI
@deftypefun double sinh (double @var{x})
The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}. The
function fails, and sets @code{errno} to @code{ERANGE}, if the value of
@var{x} is too large; that is, if overflow occurs.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double cosh (double @var{x})
The @code{cosh} function returns the hyperbolic cosine of @var{x},
defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
The function fails, and sets @code{errno} to @code{ERANGE}, if the value
of @var{x} is too large; that is, if overflow occurs.
@end deftypefun
@comment math.h
@comment ANSI
@deftypefun double tanh (double @var{x})
This function returns the hyperbolic tangent of @var{x}, whose
mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
@end deftypefun
@cindex inverse hyperbolic functions
@comment math.h
@comment BSD
@deftypefun double asinh (double @var{x})
This function returns the inverse hyperbolic sine of @var{x}---the
value whose hyperbolic sine is @var{x}.
@end deftypefun
@comment math.h
@comment BSD
@deftypefun double acosh (double @var{x})
This function returns the inverse hyperbolic cosine of @var{x}---the
value whose hyperbolic cosine is @var{x}. If @var{x} is less than
@code{1}, @code{acosh} returns @code{HUGE_VAL}.
@end deftypefun
@comment math.h
@comment BSD
@deftypefun double atanh (double @var{x})
This function returns the inverse hyperbolic tangent of @var{x}---the
value whose hyperbolic tangent is @var{x}. If the absolute value of
@var{x} is greater than or equal to @code{1}, @code{atanh} returns
@code{HUGE_VAL}.
@end deftypefun
@node Pseudo-Random Numbers
@section Pseudo-Random Numbers
@cindex random numbers
@cindex pseudo-random numbers
@cindex seed (for random numbers)
This section describes the GNU facilities for generating a series of
pseudo-random numbers. The numbers generated are not truly random;
typically, they form a sequence that repeats periodically, with a
period so large that you can ignore it for ordinary purposes. The
random number generator works by remembering at all times a @dfn{seed}
value which it uses to compute the next random number and also to
compute a new seed.
Although the generated numbers look unpredictable within one run of a
program, the sequence of numbers is @emph{exactly the same} from one run
to the next. This is because the initial seed is always the same. This
is convenient when you are debugging a program, but it is unhelpful if
you want the program to behave unpredictably. If you want truly random
numbers, not just pseudo-random, specify a seed based on the current
time.
You can get repeatable sequences of numbers on a particular machine type
by specifying the same initial seed value for the random number
generator. There is no standard meaning for a particular seed value;
the same seed, used in different C libraries or on different CPU types,
will give you different random numbers.
The GNU library supports the standard ANSI C random number functions
plus another set derived from BSD. We recommend you use the standard
ones, @code{rand} and @code{srand}.
@menu
* ANSI Random:: @code{rand} and friends.
* BSD Random:: @code{random} and friends.
@end menu
@node ANSI Random
@subsection ANSI C Random Number Functions
This section describes the random number functions that are part of
the ANSI C standard.
To use these facilities, you should include the header file
@file{stdlib.h} in your program.
@pindex stdlib.h
@comment stdlib.h
@comment ANSI
@deftypevr Macro int RAND_MAX
The value of this macro is an integer constant expression that
represents the maximum possible value returned by the @code{rand}
function. In the GNU library, it is @code{037777777}, which is the
largest signed integer representable in 32 bits. In other libraries, it
may be as low as @code{32767}.
@end deftypevr
@comment stdlib.h
@comment ANSI
@deftypefun int rand ()
The @code{rand} function returns the next pseudo-random number in the
series. The value is in the range from @code{0} to @code{RAND_MAX}.
@end deftypefun
@comment stdlib.h
@comment ANSI
@deftypefun void srand (unsigned int @var{seed})
This function establishes @var{seed} as the seed for a new series of
pseudo-random numbers. If you call @code{rand} before a seed has been
established with @code{srand}, it uses the value @code{1} as a default
seed.
To produce truly random numbers (not just pseudo-random), do @code{srand
(time (0))}.
@end deftypefun
@node BSD Random
@subsection BSD Random Number Functions
This section describes a set of random number generation functions that
are derived from BSD. There is no advantage to using these functions
with the GNU C library; we support them for BSD compatibility only.
The prototypes for these functions are in @file{stdlib.h}.
@pindex stdlib.h
@comment stdlib.h
@comment BSD
@deftypefun {long int} random ()
This function returns the next pseudo-random number in the sequence.
The range of values returned is from @code{0} to @code{RAND_MAX}.
@end deftypefun
@comment stdlib.h
@comment BSD
@deftypefun void srandom (unsigned int @var{seed})
The @code{srandom} function sets the seed for the current random number
state based on the integer @var{seed}. If you supply a @var{seed} value
of @code{1}, this will cause @code{random} to reproduce the default set
of random numbers.
To produce truly random numbers (not just pseudo-random), do
@code{srandom (time (0))}.
@end deftypefun
@comment stdlib.h
@comment BSD
@deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
The @code{initstate} function is used to initialize the random number
generator state. The argument @var{state} is an array of @var{size}
bytes, used to hold the state information. The size must be at least 8
bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256. The bigger
the @var{state} array, the better.
The return value is the previous value of the state information array.
You can use this value later as an argument to @code{setstate} to
restore that state.
@end deftypefun
@comment stdlib.h
@comment BSD
@deftypefun {void *} setstate (void *@var{state})
The @code{setstate} function restores the random number state
information @var{state}. The argument must have been the result of
a previous call to @var{initstate} or @var{setstate}.
The return value is the previous value of the state information array.
You can use thise value later as an argument to @code{setstate} to
restore that state.
@end deftypefun