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 2010-09-20 "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 functions return the next representable floating-point value following
  74 .I x
  75 in the direction of
  76 .IR y .
  77 If
  78 .I y
  79 is less than
  80 .IR x ,
  81 these functions will return the largest representable number less than
  82 .IR x .
  83
  84 If
  85 .I x
  86 equals
  87 .IR y ,
  88 the functions return
  89 .IR y .
  90
  91 The
  92 .BR nexttoward ()
  93 functions do the same as the
  94 .BR nextafter ()
  95 functions, except that they have a
  96 .I "long double"
  97 second argument.
  98 .SH RETURN VALUE
  99 On success,
 100 these functions return the next representable floating-point value after
 101 .I x
 102 in the direction of
 103 .IR y .
 104
 105 If
 106 .I x
 107 equals
 108 .IR y ,
 109 then
 110 .I y
 111 (cast to the same type as
 112 .IR x )
 113 is returned.
 114
 115 If
 116 .I x
 117 or
 118 .I y
 119 is a NaN,
 120 a NaN is returned.
 121
 122 If
 123 .I x
 124 is finite,
 125 .\" e.g., DBL_MAX
 126 and the result would overflow,
 127 a range error occurs,
 128 and the functions return
 129 .BR HUGE_VAL ,
 130 .BR HUGE_VALF ,
 131 or
 132 .BR HUGE_VALL ,
 133 respectively, with the correct mathematical sign.
 134
 135 If
 136 .I x
 137 is not equal to
 138 .IR y ,
 139 and the correct function result would be subnormal, zero, or underflow,
 140 a range error occurs,
 141 and either the correct value (if it can be represented),
 142 or 0.0, is returned.
 143 .SH ERRORS
 144 See
 145 .BR math_error (7)
 146 for information on how to determine whether an error has occurred
 147 when calling these functions.
 148 .PP
 149 The following errors can occur:
 150 .TP
 151 Range error: result overflow
 152 .\" e.g., nextafter(DBL_MAX, HUGE_VAL);
 153 .\" .I errno
 154 .\" is set to
 155 .\" .BR ERANGE .
 156 An overflow floating-point exception
 157 .RB ( FE_OVERFLOW )
 158 is raised.
 159 .TP
 160 Range error: result is subnormal or underflows
 161 .\" e.g., nextafter(DBL_MIN, 0.0);
 162 .\" .I errno
 163 .\" is set to
 164 .\" .BR ERANGE .
 165 An underflow floating-point exception
 166 .RB ( FE_UNDERFLOW )
 167 is raised.
 168 .PP
 169 These functions do not set
 170 .IR errno .
 171 .\" FIXME . Is it intentional that these functions do not set errno?
 172 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799
 173 .SH CONFORMING TO
 174 C99, POSIX.1-2001.
 175 This function is defined in IEC 559 (and the appendix with
 176 recommended functions in IEEE 754/IEEE 854).
 177 .SH BUGS
 178 In glibc version 2.5 and earlier, these functions do not raise an underflow
 179 floating-point
 180 .RB ( FE_UNDERFLOW )
 181 exception when an underflow occurs.
 182 .SH SEE ALSO
 183 .BR nearbyint (3)