man3/nextafter.3

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