Debian Codegraph @

upstream/debian-unstable/man3/nextafter.3

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