man3/remainder.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 .\"
  13 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  14 .\" Modified 2002-08-10 Walter Harms
  15 .\"     (walter.harms@informatik.uni-oldenburg.de)
  16 .\" Modified 2003-11-18, 2004-10-05 aeb
  17 .\"
  18 .TH remainder 3 (date) "Linux man-pages (unreleased)"
  19 .SH NAME
  20 drem, dremf, dreml, remainder, remainderf, remainderl \- \
  21 floating-point remainder function
  22 .SH LIBRARY
  23 Math library
  24 .RI ( libm ", " \-lm )
  25 .SH SYNOPSIS
  26 .nf
  27 .B #include <math.h>
  28 .P
  29 .BI "double remainder(double " x ", double " y );
  30 .BI "float remainderf(float " x ", float " y );
  31 .BI "long double remainderl(long double " x ", long double " y );
  32 .P
  33 /* Obsolete synonyms */
  34 .BI "[[deprecated]] double drem(double " x ", double " y );
  35 .BI "[[deprecated]] float dremf(float " x ", float " y );
  36 .BI "[[deprecated]] long double dreml(long double " x ", long double " y );
  37 .fi
  38 .P
  39 .RS -4
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .RE
  43 .P
  44 .BR remainder ():
  45 .nf
  46     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  47         || _XOPEN_SOURCE >= 500
  48 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  49         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  50         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  51 .fi
  52 .P
  53 .BR remainderf (),
  54 .BR remainderl ():
  55 .nf
  56     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  57         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  58         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  59 .fi
  60 .P
  61 .BR drem (),
  62 .BR dremf (),
  63 .BR dreml ():
  64 .nf
  65     /* Since glibc 2.19: */ _DEFAULT_SOURCE
  66         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  67 .fi
  68 .SH DESCRIPTION
  69 These
  70 functions compute the remainder of dividing
  71 .I x
  72 by
  73 .IR y .
  74 The return value is
  75 \fIx\fP\-\fIn\fP*\fIy\fP,
  76 where
  77 .I n
  78 is the value
  79 .IR "x\ /\ y" ,
  80 rounded to the nearest integer.
  81 If the absolute value of
  82 \fIx\fP\-\fIn\fP*\fIy\fP
  83 is 0.5,
  84 .I n
  85 is chosen to be even.
  86 .P
  87 These functions are unaffected by the current rounding mode (see
  88 .BR fenv (3)).
  89 .P
  90 The
  91 .BR drem ()
  92 function does precisely the same thing.
  93 .SH RETURN VALUE
  94 On success, these
  95 functions return the floating-point remainder,
  96 \fIx\fP\-\fIn\fP*\fIy\fP.
  97 If the return value is 0, it has the sign of
  98 .IR x .
  99 .P
 100 If
 101 .I x
 102 or
 103 .I y
 104 is a NaN, a NaN is returned.
 105 .P
 106 If
 107 .I x
 108 is an infinity,
 109 and
 110 .I y
 111 is not a NaN,
 112 a domain error occurs, and
 113 a NaN is returned.
 114 .P
 115 If
 116 .I y
 117 is zero,
 118 .\" FIXME . Instead, glibc gives a domain error even if x is a NaN
 119 and
 120 .I x
 121 is not a NaN,
 122 .\" Interestingly, remquo(3) does not have the same problem.
 123 a domain error occurs, and
 124 a NaN is returned.
 125 .SH ERRORS
 126 See
 127 .BR math_error (7)
 128 for information on how to determine whether an error has occurred
 129 when calling these functions.
 130 .P
 131 The following errors can occur:
 132 .TP
 133 Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN
 134 .I errno
 135 is set to
 136 .B EDOM
 137 (but see BUGS).
 138 An invalid floating-point exception
 139 .RB ( FE_INVALID )
 140 is raised.
 141 .IP
 142 These functions do not set
 143 .I errno
 144 for this case.
 145 .TP
 146 Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN
 147 .I errno
 148 is set to
 149 .BR EDOM .
 150 An invalid floating-point exception
 151 .RB ( FE_INVALID )
 152 is raised.
 153 .SH ATTRIBUTES
 154 For an explanation of the terms used in this section, see
 155 .BR attributes (7).
 156 .TS
 157 allbox;
 158 lbx lb lb
 159 l l l.
 160 Interface       Attribute       Value
 161 T{
 162 .na
 163 .nh
 164 .BR drem (),
 165 .BR dremf (),
 166 .BR dreml (),
 167 .BR remainder (),
 168 .BR remainderf (),
 169 .BR remainderl ()
 170 T}      Thread safety   MT-Safe
 171 .TE
 172 .SH STANDARDS
 173 .\" IEC 60559.
 174 .TP
 175 .BR remainder ()
 176 .TQ
 177 .BR remainderf ()
 178 .TQ
 179 .BR remainderl ()
 180 C11, POSIX.1-2008.
 181 .TP
 182 .BR drem ()
 183 .TQ
 184 .BR dremf ()
 185 .TQ
 186 .BR dreml ()
 187 None.
 188 .SH HISTORY
 189 .\" IEC 60559.
 190 .TP
 191 .BR remainder ()
 192 .TQ
 193 .BR remainderf ()
 194 .TQ
 195 .BR remainderl ()
 196 C99, POSIX.1-2001.
 197 .TP
 198 .BR drem ()
 199 4.3BSD.
 200 .TP
 201 .BR dremf ()
 202 .TQ
 203 .BR dreml ()
 204 Tru64, glibc2.
 205 .SH BUGS
 206 Before glibc 2.15,
 207 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779
 208 the call
 209 .P
 210 .in +4n
 211 .EX
 212 remainder(nan(""), 0);
 213 .EE
 214 .in
 215 .P
 216 returned a NaN, as expected, but wrongly caused a domain error.
 217 Since glibc 2.15, a silent NaN (i.e., no domain error) is returned.
 218 .P
 219 Before glibc 2.15,
 220 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6783
 221 .I errno
 222 was not set to
 223 .B EDOM
 224 for the domain error that occurs when
 225 .I x
 226 is an infinity and
 227 .I y
 228 is not a NaN.
 229 .SH EXAMPLES
 230 The call "remainder(29.0, 3.0)" returns \-1.
 231 .SH SEE ALSO
 232 .BR div (3),
 233 .BR fmod (3),
 234 .BR remquo (3)