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 2015-04-19 "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 .sp
  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 .sp
  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 .sp
  30 Link with \fI\-lm\fP.
  31 .sp
  32 .in -4n
  33 Feature Test Macro Requirements for glibc (see
  34 .BR feature_test_macros (7)):
  35 .in
  36 .sp
  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 .br
  46 or
  47 .I cc\ -std=c99
  48 .RE
  49 .br
  50 .BR nextafterf (),
  51 .BR nextafterl ():
  52 .RS 4
  53 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  54     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  55     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  56 .br
  57 or
  58 .I cc\ -std=c99
  59 .RE
  60 .br
  61 .BR nexttoward (),
  62 .BR nexttowardf (),
  63 .BR nexttowardl ():
  64 .RS 4
  65 _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE ||
  66 _POSIX_C_SOURCE\ >=\ 200112L
  67 .br
  68 or
  69 .I cc\ -std=c99
  70 .RE
  71 .ad b
  72 .SH DESCRIPTION
  73 The
  74 .BR nextafter (),
  75 .BR nextafterf (),
  76 and
  77 .BR nextafterl ()
  78 functions return the next representable floating-point value following
  79 .I x
  80 in the direction of
  81 .IR y .
  82 If
  83 .I y
  84 is less than
  85 .IR x ,
  86 these functions will return the largest representable number less than
  87 .IR x .
  88
  89 If
  90 .I x
  91 equals
  92 .IR y ,
  93 the functions return
  94 .IR y .
  95
  96 The
  97 .BR nexttoward (),
  98 .BR nexttowardf (),
  99 and
 100 .BR nexttowardl ()
 101 functions do the same as the corresponding
 102 .BR nextafter ()
 103 functions, except that they have a
 104 .I "long double"
 105 second argument.
 106 .SH RETURN VALUE
 107 On success,
 108 these functions return the next representable floating-point value after
 109 .I x
 110 in the direction of
 111 .IR y .
 112
 113 If
 114 .I x
 115 equals
 116 .IR y ,
 117 then
 118 .I y
 119 (cast to the same type as
 120 .IR x )
 121 is returned.
 122
 123 If
 124 .I x
 125 or
 126 .I y
 127 is a NaN,
 128 a NaN is returned.
 129
 130 If
 131 .I x
 132 is finite,
 133 .\" e.g., DBL_MAX
 134 and the result would overflow,
 135 a range error occurs,
 136 and the functions return
 137 .BR HUGE_VAL ,
 138 .BR HUGE_VALF ,
 139 or
 140 .BR HUGE_VALL ,
 141 respectively, with the correct mathematical sign.
 142
 143 If
 144 .I x
 145 is not equal to
 146 .IR y ,
 147 and the correct function result would be subnormal, zero, or underflow,
 148 a range error occurs,
 149 and either the correct value (if it can be represented),
 150 or 0.0, is returned.
 151 .SH ERRORS
 152 See
 153 .BR math_error (7)
 154 for information on how to determine whether an error has occurred
 155 when calling these functions.
 156 .PP
 157 The following errors can occur:
 158 .TP
 159 Range error: result overflow
 160 .\" e.g., nextafter(DBL_MAX, HUGE_VAL);
 161 .\" .I errno
 162 .\" is set to
 163 .\" .BR ERANGE .
 164 An overflow floating-point exception
 165 .RB ( FE_OVERFLOW )
 166 is raised.
 167 .TP
 168 Range error: result is subnormal or underflows
 169 .\" e.g., nextafter(DBL_MIN, 0.0);
 170 .\" .I errno
 171 .\" is set to
 172 .\" .BR ERANGE .
 173 An underflow floating-point exception
 174 .RB ( FE_UNDERFLOW )
 175 is raised.
 176 .PP
 177 These functions do not set
 178 .IR errno .
 179 .\" FIXME . Is it intentional that these functions do not set errno?
 180 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799
 181 .SH ATTRIBUTES
 182 For an explanation of the terms used in this section, see
 183 .BR attributes (7).
 184 .TS
 185 allbox;
 186 lbw28 lb lb
 187 l l l.
 188 Interface       Attribute       Value
 189 T{
 190 .BR nextafter (),
 191 .BR nextafterf (),
 192 .br
 193 .BR nextafterl (),
 194 .BR nexttoward (),
 195 .br
 196 .BR nexttowardf (),
 197 .BR nexttowardl ()
 198 T}      Thread safety   MT-Safe
 199 .TE
 200 .SH CONFORMING TO
 201 C99, POSIX.1-2001, POSIX.1-2008.
 202 This function is defined in IEC 559 (and the appendix with
 203 recommended functions in IEEE 754/IEEE 854).
 204 .SH BUGS
 205 In glibc version 2.5 and earlier, these functions do not raise an underflow
 206 floating-point
 207 .RB ( FE_UNDERFLOW )
 208 exception when an underflow occurs.
 209 .SH SEE ALSO
 210 .BR nearbyint (3)