man3/nextafter.3

   1 .\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   6 .\" Distributed under GPL
   7 .\" %%%LICENSE_END
   8 .\"
   9 .\" Based on glibc infopages
  10 .\"
  11 .TH NEXTAFTER 3 2017-09-15 "GNU" "Linux Programmer's Manual"
  12 .SH NAME
  13 nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \-
  14 floating-point number manipulation
  15 .SH SYNOPSIS
  16 .B #include <math.h>
  17 .PP
  18 .BI "double nextafter(double " x ", double " y );
  19 .br
  20 .BI "float nextafterf(float " x ", float " y );
  21 .br
  22 .BI "long double nextafterl(long double " x ", long double " y );
  23 .PP
  24 .BI "double nexttoward(double " x ", long double " y );
  25 .br
  26 .BI "float nexttowardf(float " x ", long double " y );
  27 .br
  28 .BI "long double nexttowardl(long double " x ", long double " y );
  29 .PP
  30 Link with \fI\-lm\fP.
  31 .PP
  32 .in -4n
  33 Feature Test Macro Requirements for glibc (see
  34 .BR feature_test_macros (7)):
  35 .in
  36 .PP
  37 .ad l
  38 .BR nextafter ():
  39 .RS 4
  40 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  41     || _XOPEN_SOURCE\ >=\ 500
  42 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  43     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  44     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  45 .RE
  46 .br
  47 .BR nextafterf (),
  48 .BR nextafterl ():
  49 .RS 4
  50 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  51     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  52     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  53 .RE
  54 .br
  55 .BR nexttoward (),
  56 .BR nexttowardf (),
  57 .BR nexttowardl ():
  58 .RS 4
  59 _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE ||
  60 _POSIX_C_SOURCE\ >=\ 200112L
  61 .RE
  62 .ad b
  63 .SH DESCRIPTION
  64 The
  65 .BR nextafter (),
  66 .BR nextafterf (),
  67 and
  68 .BR nextafterl ()
  69 functions return the next representable floating-point value following
  70 .I x
  71 in the direction of
  72 .IR y .
  73 If
  74 .I y
  75 is less than
  76 .IR x ,
  77 these functions will return the largest representable number less than
  78 .IR x .
  79 .PP
  80 If
  81 .I x
  82 equals
  83 .IR y ,
  84 the functions return
  85 .IR y .
  86 .PP
  87 The
  88 .BR nexttoward (),
  89 .BR nexttowardf (),
  90 and
  91 .BR nexttowardl ()
  92 functions do the same as the corresponding
  93 .BR nextafter ()
  94 functions, except that they have a
  95 .I "long double"
  96 second argument.
  97 .SH RETURN VALUE
  98 On success,
  99 these functions return the next representable floating-point value after
 100 .I x
 101 in the direction of
 102 .IR y .
 103 .PP
 104 If
 105 .I x
 106 equals
 107 .IR y ,
 108 then
 109 .I y
 110 (cast to the same type as
 111 .IR x )
 112 is returned.
 113 .PP
 114 If
 115 .I x
 116 or
 117 .I y
 118 is a NaN,
 119 a NaN is returned.
 120 .PP
 121 If
 122 .I x
 123 is finite,
 124 .\" e.g., DBL_MAX
 125 and the result would overflow,
 126 a range error occurs,
 127 and the functions return
 128 .BR HUGE_VAL ,
 129 .BR HUGE_VALF ,
 130 or
 131 .BR HUGE_VALL ,
 132 respectively, with the correct mathematical sign.
 133 .PP
 134 If
 135 .I x
 136 is not equal to
 137 .IR y ,
 138 and the correct function result would be subnormal, zero, or underflow,
 139 a range error occurs,
 140 and either the correct value (if it can be represented),
 141 or 0.0, is returned.
 142 .SH ERRORS
 143 See
 144 .BR math_error (7)
 145 for information on how to determine whether an error has occurred
 146 when calling these functions.
 147 .PP
 148 The following errors can occur:
 149 .TP
 150 Range error: result overflow
 151 .\" e.g., nextafter(DBL_MAX, HUGE_VAL);
 152 .I errno
 153 is set to
 154 .BR ERANGE .
 155 An overflow floating-point exception
 156 .RB ( FE_OVERFLOW )
 157 is raised.
 158 .TP
 159 Range error: result is subnormal or underflows
 160 .\" e.g., nextafter(DBL_MIN, 0.0);
 161 .I errno
 162 is set to
 163 .BR ERANGE .
 164 An underflow floating-point exception
 165 .RB ( FE_UNDERFLOW )
 166 is raised.
 167 .SH ATTRIBUTES
 168 For an explanation of the terms used in this section, see
 169 .BR attributes (7).
 170 .TS
 171 allbox;
 172 lbw28 lb lb
 173 l l l.
 174 Interface       Attribute       Value
 175 T{
 176 .BR nextafter (),
 177 .BR nextafterf (),
 178 .br
 179 .BR nextafterl (),
 180 .BR nexttoward (),
 181 .br
 182 .BR nexttowardf (),
 183 .BR nexttowardl ()
 184 T}      Thread safety   MT-Safe
 185 .TE
 186 .SH CONFORMING TO
 187 C99, POSIX.1-2001, POSIX.1-2008.
 188 This function is defined in IEC 559 (and the appendix with
 189 recommended functions in IEEE 754/IEEE 854).
 190 .SH BUGS
 191 In glibc version 2.5 and earlier, these functions do not raise an underflow
 192 floating-point
 193 .RB ( FE_UNDERFLOW )
 194 exception when an underflow occurs.
 195 .SH BUGS
 196 Before glibc version 2.23
 197 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6799
 198 these functions did not set
 199 .IR errno .
 200 .SH SEE ALSO
 201 .BR nearbyint (3)