Debian Codegraph @

upstream/debian-unstable/man3/fmod.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH fmod 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 fmod, fmodf, fmodl \- floating-point remainder function
10 .SH LIBRARY
11 Math library
12 .RI ( libm ,\~ \-lm )
13 .SH SYNOPSIS
14 .nf
15 .B #include <math.h>
16 .P
17 .BI "double fmod(double " x ", double " y );
18 .BI "float fmodf(float " x ", float " y );
19 .BI "long double fmodl(long double " x ", long double " y );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR fmodf (),
28 .BR fmodl ():
29 .nf
30 _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
31 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
32 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
33 .fi
34 .SH DESCRIPTION
35 These functions compute the floating-point remainder of dividing
36 .I x
37 by
38 .IR y .
39 The return value is
40 .I x
41 \-
42 .I n
43 *
44 .IR y ,
45 where
46 .I n
47 is the quotient of
48 .I x
49 /
50 .IR y ,
51 rounded toward zero to an integer.
52 .P
53 To obtain the modulus, more specifically, the Least Positive Residue,
54 you will need to adjust the result from
55 .BR fmod ()
56 like so:
57 .P
58 .in +4n
59 .nf
60 z = fmod(x, y);
61 if (z < 0)
62 z += fabs(y);
63 .fi
64 .in
65 .P
66 An alternate way to express this is with
67 .IR "fmod(fmod(x, y) + y, y)" ,
68 but the second
69 .BR fmod ()
70 usually costs way more than the one branch.
71 .SH RETURN VALUE
72 On success, these
73 functions return the value
74 .IR "x\ \-\ n*y" ,
75 for some integer
76 .IR n ,
77 such that the returned value has the same sign as
78 .I x
79 and a magnitude less than the magnitude of
80 .IR y .
81 .P
82 If
83 .I x
84 or
85 .I y
86 is a NaN, a NaN is returned.
87 .P
88 If
89 .I x
90 is an infinity,
91 a domain error occurs, and
92 a NaN is returned.
93 .P
94 If
95 .I y
96 is zero,
97 a domain error occurs, and
98 a NaN is returned.
99 .P
100 If
101 .I x
102 is +0 (\-0), and
103 .I y
104 is not zero, +0 (\-0) is returned.
105 .SH ERRORS
106 See
107 .BR math_error (7)
108 for information on how to determine whether an error has occurred
109 when calling these functions.
110 .P
111 The following errors can occur:
112 .TP
113 Domain error: \f[I]x\f[] is an infinity
114 .I errno
115 is set to
116 .B EDOM
117 (but see BUGS).
118 An invalid floating-point exception
119 .RB ( FE_INVALID )
120 is raised.
121 .TP
122 Domain error: \f[I]y\f[] is zero
123 .I errno
124 is set to
125 .BR EDOM .
126 An invalid floating-point exception
127 .RB ( FE_INVALID )
128 is raised.
129 .\" POSIX.1 documents an optional underflow error, but AFAICT it doesn't
130 .\" (can't?) occur -- mtk, Jul 2008
131 .SH ATTRIBUTES
132 For an explanation of the terms used in this section, see
133 .BR attributes (7).
134 .TS
135 allbox;
136 lbx lb lb
137 l l l.
138 Interface Attribute Value
139 T{
140 .na
141 .nh
142 .BR fmod (),
143 .BR fmodf (),
144 .BR fmodl ()
145 T} Thread safety MT-Safe
146 .TE
147 .SH STANDARDS
148 C11, POSIX.1-2008.
149 .SH HISTORY
150 C99, POSIX.1-2001.
151 .P
152 The variant returning
153 .I double
154 also conforms to
155 SVr4, 4.3BSD, C89.
156 .SH BUGS
157 Before glibc 2.10, the glibc implementation did not set
158 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6784
159 .I errno
160 to
161 .B EDOM
162 when a domain error occurred for an infinite
163 .IR x .
164 .SH EXAMPLES
165 The call
166 .I fmod(372, 360)
167 returns 12.
168 .P
169 The call
170 .I fmod(\-372, 360)
171 returns \-12.
172 .P
173 The call
174 .I fmod(\-372, \-360)
175 also returns \-12.
176 .SH SEE ALSO
177 .BR remainder (3)