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