Merging upstream version 6.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 39 insertions, 11 deletions

diff --git a/man3/fmod.3 b/man3/fmod.3
index e524514..dfca42e 100644
--- a/man3/fmod.3
+++ b/man3/fmod.3
@@ -13,7 +13,7 @@
 .\" Modified 2002-07-27 by Walter Harms
 .\" 	(walter.harms@informatik.uni-oldenburg.de)
 .\"
-.TH fmod 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH fmod 3 2023-10-31 "Linux man-pages 6.7"
 .SH NAME
 fmod, fmodf, fmodl \- floating-point remainder function
 .SH LIBRARY
@@ -22,17 +22,17 @@ Math library
 .SH SYNOPSIS
 .nf
 .B #include <math.h>
-.PP
+.P
 .BI "double fmod(double " x ", double " y );
 .BI "float fmodf(float " x ", float " y );
 .BI "long double fmodl(long double " x ", long double " y );
 .fi
-.PP
+.P
 .RS -4
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .RE
-.PP
+.P
 .BR fmodf (),
 .BR fmodl ():
 .nf
@@ -58,6 +58,23 @@ is the quotient of
 /
 .IR y ,
 rounded toward zero to an integer.
+.P
+To obtain the modulus, more specifically, the Least Positive Residue,
+you will need to adjust the result from fmod like so:
+.P
+.in +4n
+.nf
+z = fmod(x, y);
+if (z < 0)
+	z += y;
+.fi
+.in
+.P
+An alternate way to express this is with
+.IR "fmod(fmod(x, y) + y, y)" ,
+but the second
+.BR fmod ()
+usually costs way more than the one branch.
 .SH RETURN VALUE
 On success, these
 functions return the value \fIx\fP\ \-\ \fIn\fP*\fIy\fP,
@@ -67,25 +84,25 @@ such that the returned value has the same sign as
 .I x
 and a magnitude less than the magnitude of
 .IR y .
-.PP
+.P
 If
 .I x
 or
 .I y
 is a NaN, a NaN is returned.
-.PP
+.P
 If
 .I x
 is an infinity,
 a domain error occurs, and
 a NaN is returned.
-.PP
+.P
 If
 .I y
 is zero,
 a domain error occurs, and
 a NaN is returned.
-.PP
+.P
 If
 .I x
 is +0 (\-0), and
@@ -96,7 +113,7 @@ See
 .BR math_error (7)
 for information on how to determine whether an error has occurred
 when calling these functions.
-.PP
+.P
 The following errors can occur:
 .TP
 Domain error: \fIx\fP is an infinity
@@ -133,12 +150,11 @@ T{
 .BR fmodl ()
 T}	Thread safety	MT-Safe
 .TE
-.sp 1
 .SH STANDARDS
 C11, POSIX.1-2008.
 .SH HISTORY
 C99, POSIX.1-2001.
-.PP
+.P
 The variant returning
 .I double
 also conforms to
@@ -151,5 +167,17 @@ to
 .B EDOM
 when a domain error occurred for an infinite
 .IR x .
+.SH EXAMPLES
+The call
+.I fmod(372, 360)
+returns 348.
+.P
+The call
+.I fmod(-372, 360)
+returns -12.
+.P
+The call
+.I fmod(-372, -360)
+also returns -12.
 .SH SEE ALSO
 .BR remainder (3)