lib/libm/man/nextafter.3

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