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 \fIx\fP equals \fIy\fP, the functions return \fIy\fP.
  85
  86 The
  87 .BR nexttoward ()
  88 functions do the same as the
  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
 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
 110 If
 111 .I x
 112 or
 113 .I y
 114 is a NaN,
 115 a NaN is returned.
 116
 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
 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 .PP
 164 These functions do not set
 165 .IR errno .
 166 .\" FIXME . Is it intentional that these functions do not set errno?
 167 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799
 168 .SH CONFORMING TO
 169 C99, POSIX.1-2001.
 170 This function is defined in IEC 559 (and the appendix with
 171 recommended functions in IEEE 754/IEEE 854).
 172 .SH BUGS
 173 In glibc version 2.5 and earlier, these functions do not raise an underflow
 174 floating-point
 175 .RB ( FE_UNDERFLOW )
 176 exception when an underflow occurs.
 177 .SH SEE ALSO
 178 .BR nearbyint (3)