man3/fmod.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   4 .\"     <mtk.manpages@gmail.com>
   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 (faith@cs.unc.edu)
  13 .\" Modified 2002-07-27 by Walter Harms
  14 .\"     (walter.harms@informatik.uni-oldenburg.de)
  15 .\"
  16 .TH fmod 3 (date) "Linux man-pages (unreleased)"
  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 fmod like so:
  64 .P
  65 .in +4n
  66 .nf
  67 z = fmod(x, y);
  68 if (z < 0)
  69         z += y;
  70 .fi
  71 .in
  72 .P
  73 An alternate way to express this is with
  74 .IR "fmod(fmod(x, y) + y, y)" ,
  75 but the second
  76 .BR fmod ()
  77 usually costs way more than the one branch.
  78 .SH RETURN VALUE
  79 On success, these
  80 functions return the value \fIx\fP\ \-\ \fIn\fP*\fIy\fP,
  81 for some integer
  82 .IR n ,
  83 such that the returned value has the same sign as
  84 .I x
  85 and a magnitude less than the magnitude of
  86 .IR y .
  87 .P
  88 If
  89 .I x
  90 or
  91 .I y
  92 is a NaN, a NaN is returned.
  93 .P
  94 If
  95 .I x
  96 is an infinity,
  97 a domain error occurs, and
  98 a NaN is returned.
  99 .P
 100 If
 101 .I y
 102 is zero,
 103 a domain error occurs, and
 104 a NaN is returned.
 105 .P
 106 If
 107 .I x
 108 is +0 (\-0), and
 109 .I y
 110 is not zero, +0 (\-0) is returned.
 111 .SH ERRORS
 112 See
 113 .BR math_error (7)
 114 for information on how to determine whether an error has occurred
 115 when calling these functions.
 116 .P
 117 The following errors can occur:
 118 .TP
 119 Domain error: \fIx\fP is an infinity
 120 .I errno
 121 is set to
 122 .B EDOM
 123 (but see BUGS).
 124 An invalid floating-point exception
 125 .RB ( FE_INVALID )
 126 is raised.
 127 .TP
 128 Domain error: \fIy\fP is zero
 129 .I errno
 130 is set to
 131 .BR EDOM .
 132 An invalid floating-point exception
 133 .RB ( FE_INVALID )
 134 is raised.
 135 .\" POSIX.1 documents an optional underflow error, but AFAICT it doesn't
 136 .\" (can't?) occur -- mtk, Jul 2008
 137 .SH ATTRIBUTES
 138 For an explanation of the terms used in this section, see
 139 .BR attributes (7).
 140 .TS
 141 allbox;
 142 lbx lb lb
 143 l l l.
 144 Interface       Attribute       Value
 145 T{
 146 .na
 147 .nh
 148 .BR fmod (),
 149 .BR fmodf (),
 150 .BR fmodl ()
 151 T}      Thread safety   MT-Safe
 152 .TE
 153 .SH STANDARDS
 154 C11, POSIX.1-2008.
 155 .SH HISTORY
 156 C99, POSIX.1-2001.
 157 .P
 158 The variant returning
 159 .I double
 160 also conforms to
 161 SVr4, 4.3BSD, C89.
 162 .SH BUGS
 163 Before glibc 2.10, the glibc implementation did not set
 164 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6784
 165 .I errno
 166 to
 167 .B EDOM
 168 when a domain error occurred for an infinite
 169 .IR x .
 170 .SH EXAMPLES
 171 The call
 172 .I fmod(372, 360)
 173 returns 348.
 174 .P
 175 The call
 176 .I fmod(-372, 360)
 177 returns -12.
 178 .P
 179 The call
 180 .I fmod(-372, -360)
 181 also returns -12.
 182 .SH SEE ALSO
 183 .BR remainder (3)