lib/libm/man/scalbn.3

   1 .\" $NetBSD: scalbn.3,v 1.2 2011/09/18 05:33:14 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd September 18, 2011
  28 .Dt SCALBN 3
  29 .Os
  30 .Sh NAME
  31 .Nm scalbn ,
  32 .Nm scalbnf ,
  33 .Nm scalbnl
  34 .Nd exponent using FLT_RADIX
  35 .Sh LIBRARY
  36 .Lb libm
  37 .Sh SYNOPSIS
  38 .In math.h
  39 .Ft double
  40 .Fn scalbn "double x" "int n"
  41 .Ft float
  42 .Fn scalbnf "float x" "int n"
  43 .Ft long double
  44 .Fn scalbnl "long double x" "int n"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn scalbn ,
  48 .Fn scalbnf ,
  49 and
  50 .Fn scalbnl
  51 functions compute
  52 .Fa x
  53 *
  54 .Fa r^n ,
  55 where
  56 .Fa r
  57 is the radix of the machine's floating point arithmetic, defined by the
  58 .Dv FLT_RADIX
  59 constant in
  60 .In float.h .
  61 The rationale is efficiency;
  62 .Fa r^n
  63 is not computed explicitly.
  64 .Sh RETURN VALUES
  65 As described above, upon successful completion, the described functions return
  66 the exponent computed using
  67 .Dv FLT_RADIX .
  68 Otherwise the following may occur:
  69 .Pp
  70 .Bl -enum -offset indent
  71 .It
  72 When the result would cause an overflow, a range error occurs and
  73 .Dv \*(Pm\*HHUGE_VAL ,
  74 .Dv \*(Pm\*HHUGE_VALF ,
  75 or
  76 .Dv \*(Pm\*HHUGE_VALL
  77 is returned according to the sign of
  78 .Fa x
  79 and the return type of the corresponding function.
  80 .It
  81 When the correct value would cause an underflow
  82 and it is not representable, a range error occurs and
  83 either 0.0 or an implementation-defined value is returned.
  84 When an underflow occurs but the correct value is representable,
  85 a range error occurs but the correct value is returned.
  86 .It
  87 If
  88 .Fa x
  89 is \*(Pm0 or \*(Pm\Inf,
  90 .Fa x
  91 is returned.
  92 Likewise, if
  93 .Fa n
  94 is zero,
  95 .Fa x
  96 is returned.
  97 If
  98 .Fa x
  99 is \*(Na, \*(Na is returned.
 100 .El
 101 .Sh SEE ALSO
 102 .Xr exp 3 ,
 103 .Xr frexp 3 ,
 104 .Xr ldexp 3 ,
 105 .Xr math 3
 106 .Sh STANDARDS
 107 The described functions conform to
 108 .St -isoC-99 .