xref: /minix3/lib/libm/man/nextafter.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
1.\" $NetBSD: nextafter.3,v 1.5 2015/09/13 10:58:30 he Exp $
2.\"
3.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\"
15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25.\" POSSIBILITY OF SUCH DAMAGE.
26.\"
27.Dd September 13, 2015
28.Dt NEXTAFTER 3
29.Os
30.Sh NAME
31.Nm nextafter ,
32.Nm nextafterf ,
33.Nm nextafterl ,
34.Nm nexttoward ,
35.Nm nexttowardf
36.\"
37.\" XXX: Not yet implemented.
38.\"
39.\" .Nm nexttowardl
40.\"
41.Nd next representable floating-point number
42.Sh LIBRARY
43.Lb libm
44.Sh SYNOPSIS
45.In math.h
46.Ft double
47.Fn nextafter "double x" "double y"
48.Ft float
49.Fn nextafterf "float x" "float y"
50.Ft long double
51.Fn nextafterl "long double x" "long double y"
52.Ft double
53.Fn nexttoward "double x" "long double y"
54.Ft float
55.Fn nexttowardf "float x" "long double y"
56.Sh DESCRIPTION
57The
58.Fn nextafter ,
59.Fn nextafterf ,
60and
61.Fn nextafterl
62functions return the next machine representable number from
63.Fa x
64in direction of
65.Fa y .
66In other words, if
67.Fa y
68is less than
69.Fa x ,
70the functions return the largest representable floating-point number less than
71.Fa x .
72When
73.Fa x
74equals
75.Fa y ,
76the value of
77.Fa y
78is returned.
79The three functions differ only in the type of the return value and
80.Fa x .
81.Pp
82The
83.Fn nexttoward
84and
85.Fn nexttowardf
86functions are equivalent to the
87.Fn nextafter
88family of functions with two exceptions:
89.Bl -enum -offset indent
90.It
91The second parameter has a type
92.Vt long double .
93.It
94The return value is
95.Fa y
96converted to the type of the function, provided that
97.Fa x
98equals
99.Fa y .
100.El
101.Sh RETURN VALUES
102Upon successful completion, the described functions return
103the next representable floating-point value as described above.
104If
105.Fa x
106is finite but an overflow would occur,
107a range error follows and the functions return
108.Dv \*(Pm\*HHUGE_VAL ,
109.Dv  \*(Pm\*HHUGE_VALF ,
110or
111.Dv  \*(Pm\*HHUGE_VALL
112with the same sign as
113.Fa x .
114When either
115.Fa x
116or
117.Fa y
118is \*(Na, a \*(Na is returned.
119When
120.Fa x
121is not
122.Fa y
123but the function value is subnormal, zero, or underflows,
124a range error occurs, and either 0.0 or the correct function
125value (if representable) is returned.
126.Sh SEE ALSO
127.Xr math 3
128.Sh STANDARDS
129The described functions conform to
130.St -isoC-99 .
131