Debian Codegraph @

upstream/fedora-44/man3/fmod.3

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