lib/libm/man/nextafter.3

   1 .\" $NetBSD: nextafter.3,v 1.4 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 NEXTAFTER 3
  29 .Os
  30 .Sh NAME
  31 .Nm nextafter ,
  32 .Nm nextafterf ,
  33 .Nm nextafterl ,
  34 .Nm nexttoward
  35 .\"
  36 .\" XXX: Not yet implemented.
  37 .\"
  38 .\" .Nm nexttowardf ,
  39 .\" .Nm nexttowardl
  40 .\"
  41 .Nd next representable floating-point number
  42 .Sh LIBRARY
  43 .Lb libm
  44 .Sh SYNOPSIS
  45 .In math.h
  46 .Ft double
  47 .Fn nextafter "double x" "double y"
  48 .Ft float
  49 .Fn nextafterf "float x" "float y"
  50 .Ft long double
  51 .Fn nextafterl "long double x" "long double y"
  52 .Ft double
  53 .Fn nexttoward "double x" "long double y"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn nextafter ,
  57 .Fn nextafterf ,
  58 and
  59 .Fn nextafterl
  60 functions return the next machine representable number from
  61 .Fa x
  62 in direction of
  63 .Fa y .
  64 In other words, if
  65 .Fa y
  66 is less than
  67 .Fa x ,
  68 the functions return the largest representable floating-point number less than
  69 .Fa x .
  70 When
  71 .Fa x
  72 equals
  73 .Fa y ,
  74 the value of
  75 .Fa y
  76 is returned.
  77 The three functions differ only in the type of the return value and
  78 .Fa x .
  79 .Pp
  80 The
  81 .Fn nexttoward
  82 function is equivalent to the
  83 .Fn nextafter
  84 family of functions with two exceptions:
  85 .Bl -enum -offset indent
  86 .It
  87 The second parameter has a type
  88 .Vt long double .
  89 .It
  90 The return value is
  91 .Fa y
  92 converted to the type of the function, provided that
  93 .Fa x
  94 equals
  95 .Fa y .
  96 .El
  97 .Sh RETURN VALUES
  98 Upon successful completion, the described functions return
  99 the next representable floating-point value as described above.
 100 If
 101 .Fa x
 102 is finite but an overflow would occur,
 103 a range error follows and the functions return
 104 .Dv \*(Pm\*HHUGE_VAL ,
 105 .Dv  \*(Pm\*HHUGE_VALF ,
 106 or
 107 .Dv  \*(Pm\*HHUGE_VALL
 108 with the same sign as
 109 .Fa x .
 110 When either
 111 .Fa x
 112 or
 113 .Fa y
 114 is \*(Na, a \*(Na is returned.
 115 When
 116 .Fa x
 117 is not
 118 .Fa y
 119 but the function value is subnormal, zero, or underflows,
 120 a range error occurs, and either 0.0 or the correct function
 121 value (if representable) is returned.
 122 .Sh SEE ALSO
 123 .Xr math 3
 124 .Sh STANDARDS
 125 The described functions conform to
 126 .St -isoC-99 .