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 .\" Distributed under GPL
   5 .\" Based on glibc infopages
   6 .TH NEXTAFTER 3 2009-12-05 "GNU" "Linux Programmer's Manual"
   7 .SH NAME
   8 nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \-
   9 floating-point number manipulation
  10 .SH SYNOPSIS
  11 .B #include <math.h>
  12 .sp
  13 .BI "double nextafter(double " x ", double " y );
  14 .br
  15 .BI "float nextafterf(float " x ", float " y );
  16 .br
  17 .BI "long double nextafterl(long double " x ", long double " y );
  18 .sp
  19 .BI "double nexttoward(double " x ", long double " y );
  20 .br
  21 .BI "float nexttowardf(float " x ", long double " y );
  22 .br
  23 .BI "long double nexttowardl(long double " x ", long double " y );
  24 .sp
  25 Link with \fI\-lm\fP.
  26 .sp
  27 .in -4n
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .in
  31 .sp
  32 .ad l
  33 .BR nextafter ():
  34 _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE; or
  35 .I cc\ -std=c99
  36 .br
  37 .BR nextafterf (),
  38 .BR nextafterl ():
  39 _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE; or
  40 .I cc\ -std=c99
  41 .br
  42 .BR nexttoward (),
  43 .BR nexttowardf (),
  44 .BR nexttowardl ():
  45 _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE;
  46 .I cc\ -std=c99
  47 .ad b
  48 .SH DESCRIPTION
  49 The
  50 .BR nextafter ()
  51 functions return the next representable floating-point value following
  52 .I x
  53 in the direction of
  54 .IR y .
  55 If
  56 .I y
  57 is less than
  58 .IR x ,
  59 these functions will return the largest representable number less than
  60 .IR x .
  61
  62 If \fIx\fP equals \fIy\fP, the functions return \fIy\fP.
  63
  64 The
  65 .BR nexttoward ()
  66 functions do the same as the
  67 .BR nextafter ()
  68 functions, except that they have a
  69 .I "long double"
  70 second argument.
  71 .SH RETURN VALUE
  72 On success,
  73 these functions return the next representable floating-point value after
  74 .I x
  75 in the direction of
  76 .IR y .
  77
  78 If
  79 .I x
  80 equals
  81 .IR y ,
  82 then
  83 .I y
  84 (cast to the same type as
  85 .IR x )
  86 is returned.
  87
  88 If
  89 .I x
  90 or
  91 .I y
  92 is a NaN,
  93 a NaN is returned.
  94
  95 If
  96 .I x
  97 is finite,
  98 .\" e.g., DBL_MAX
  99 and the result would overflow,
 100 a range error occurs,
 101 and the functions return
 102 .BR HUGE_VAL ,
 103 .BR HUGE_VALF ,
 104 or
 105 .BR HUGE_VALL ,
 106 respectively, with the correct mathematical sign.
 107
 108 If
 109 .I x
 110 is not equal to
 111 .IR y ,
 112 and the correct function result would be subnormal, zero, or underflow,
 113 a range error occurs,
 114 and either the correct value (if it can be represented),
 115 or 0.0, is returned.
 116 .SH ERRORS
 117 See
 118 .BR math_error (7)
 119 for information on how to determine whether an error has occurred
 120 when calling these functions.
 121 .PP
 122 The following errors can occur:
 123 .TP
 124 Range error: result overflow
 125 .\" e.g., nextafter(DBL_MAX, HUGE_VAL);
 126 .\" .I errno
 127 .\" is set to
 128 .\" .BR ERANGE .
 129 An overflow floating-point exception
 130 .RB ( FE_OVERFLOW )
 131 is raised.
 132 .TP
 133 Range error: result is subnormal or underflows
 134 .\" e.g., nextafter(DBL_MIN, 0.0);
 135 .\" .I errno
 136 .\" is set to
 137 .\" .BR ERANGE .
 138 An underflow floating-point exception
 139 .RB ( FE_UNDERFLOW )
 140 is raised.
 141 .PP
 142 These functions do not set
 143 .IR errno .
 144 .\" FIXME . Is it intentional that these functions do not set errno?
 145 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6799
 146 .SH "CONFORMING TO"
 147 C99, POSIX.1-2001.
 148 This function is defined in IEC 559 (and the appendix with
 149 recommended functions in IEEE 754/IEEE 854).
 150 .SH BUGS
 151 In glibc version 2.5 and earlier, these functions do not raise an underflow
 152 floating-point
 153 .RB ( FE_UNDERFLOW )
 154 exception when an underflow occurs.
 155 .SH "SEE ALSO"
 156 .BR nearbyint (3)