man3/remainder.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" References consulted:
  28 .\"     Linux libc source code
  29 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  30 .\"     386BSD man pages
  31 .\"
  32 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  33 .\" Modified 2002-08-10 Walter Harms
  34 .\"     (walter.harms@informatik.uni-oldenburg.de)
  35 .\" Modified 2003-11-18, 2004-10-05 aeb
  36 .\"
  37 .TH REMAINDER 3 2017-09-15 "" "Linux Programmer's Manual"
  38 .SH NAME
  39 drem, dremf, dreml, remainder, remainderf, remainderl \- \
  40 floating-point remainder function
  41 .SH SYNOPSIS
  42 .nf
  43 .B #include <math.h>
  44 .PP
  45 /* The C99 versions */
  46 .BI "double remainder(double " x ", double " y );
  47 .BI "float remainderf(float " x ", float " y );
  48 .BI "long double remainderl(long double " x ", long double " y );
  49 .PP
  50 /* Obsolete synonyms */
  51 .BI "double drem(double " x ", double " y );
  52 .BI "float dremf(float " x ", float " y );
  53 .BI "long double dreml(long double " x ", long double " y );
  54 .PP
  55 .fi
  56 Link with \fI\-lm\fP.
  57 .PP
  58 .in -4n
  59 Feature Test Macro Requirements for glibc (see
  60 .BR feature_test_macros (7)):
  61 .in
  62 .PP
  63 .ad l
  64 .BR remainder ():
  65 .RS 4
  66 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  67     || _XOPEN_SOURCE\ >=\ 500
  68 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  69     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  70     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  71 .RE
  72 .br
  73 .BR remainderf (),
  74 .BR remainderl ():
  75 .RS 4
  76 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  77     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  78     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  79 .RE
  80 .br
  81 .BR drem (),
  82 .BR dremf (),
  83 .BR dreml ():
  84 .RS 4
  85 /* Since glibc 2.19: */ _DEFAULT_SOURCE
  86     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  87 .RE
  88 .ad b
  89 .SH DESCRIPTION
  90 These
  91 functions compute the remainder of dividing
  92 .I x
  93 by
  94 .IR y .
  95 The return value is
  96 \fIx\fP\-\fIn\fP*\fIy\fP,
  97 where
  98 .I n
  99 is the value
 100 .IR "x\ /\ y" ,
 101 rounded to the nearest integer.
 102 If the absolute value of
 103 \fIx\fP\-\fIn\fP*\fIy\fP
 104 is 0.5,
 105 .I n
 106 is chosen to be even.
 107 .PP
 108 These functions are unaffected by the current rounding mode (see
 109 .BR fenv (3)).
 110 .PP
 111 The
 112 .BR drem ()
 113 function does precisely the same thing.
 114 .SH RETURN VALUE
 115 On success, these
 116 functions return the floating-point remainder,
 117 \fIx\fP\-\fIn\fP*\fIy\fP.
 118 If the return value is 0, it has the sign of
 119 .IR x .
 120 .PP
 121 If
 122 .I x
 123 or
 124 .I y
 125 is a NaN, a NaN is returned.
 126 .PP
 127 If
 128 .I x
 129 is an infinity,
 130 and
 131 .I y
 132 is not a NaN,
 133 a domain error occurs, and
 134 a NaN is returned.
 135 .PP
 136 If
 137 .I y
 138 is zero,
 139 .\" FIXME . Instead, glibc gives a domain error even if x is a NaN
 140 and
 141 .I x
 142 is not a NaN,
 143 .\" Interestingly, remquo(3) does not have the same problem.
 144 a domain error occurs, and
 145 a NaN is returned.
 146 .SH ERRORS
 147 See
 148 .BR math_error (7)
 149 for information on how to determine whether an error has occurred
 150 when calling these functions.
 151 .PP
 152 The following errors can occur:
 153 .TP
 154 Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN
 155 .I errno
 156 is set to
 157 .BR EDOM
 158 (but see BUGS).
 159 An invalid floating-point exception
 160 .RB ( FE_INVALID )
 161 is raised.
 162 .IP
 163 These functions do not set
 164 .IR errno
 165 for this case.
 166 .TP
 167 Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN
 168 .I errno
 169 is set to
 170 .BR EDOM .
 171 An invalid floating-point exception
 172 .RB ( FE_INVALID )
 173 is raised.
 174 .SH ATTRIBUTES
 175 For an explanation of the terms used in this section, see
 176 .BR attributes (7).
 177 .TS
 178 allbox;
 179 lbw26 lb lb
 180 l l l.
 181 Interface       Attribute       Value
 182 T{
 183 .BR drem (),
 184 .BR dremf (),
 185 .BR dreml (),
 186 .br
 187 .BR remainder (),
 188 .BR remainderf (),
 189 .br
 190 .BR remainderl ()
 191 T}      Thread safety   MT-Safe
 192 .TE
 193 .SH CONFORMING TO
 194 .\" IEC 60559.
 195 The functions
 196 .BR remainder (),
 197 .BR remainderf (),
 198 and
 199 .BR remainderl ()
 200 are specified in C99, POSIX.1-2001, and POSIX.1-2008.
 201 .PP
 202 The function
 203 .BR drem ()
 204 is from 4.3BSD.
 205 The
 206 .I float
 207 and
 208 .I "long double"
 209 variants
 210 .BR dremf ()
 211 and
 212 .BR dreml ()
 213 exist on some systems, such as Tru64 and glibc2.
 214 Avoid the use of these functions in favor of
 215 .BR remainder ()
 216 etc.
 217 .SH BUGS
 218 Before glibc 2.15,
 219 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779
 220 the call
 221 .PP
 222     remainder(nan(""), 0);
 223 .PP
 224 returned a NaN, as expected, but wrongly caused a domain error.
 225 Since glibc 2.15, a silent NaN (i.e., no domain error) is returned.
 226 .PP
 227 Before glibc 2.15,
 228 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783
 229 .I errno
 230 was not set to
 231 .BR EDOM
 232 for the domain error that occurs when
 233 .I x
 234 is an infinity and
 235 .I y
 236 is not a NaN.
 237 .I errno was not set
 238 .SH EXAMPLE
 239 The call "remainder(29.0, 3.0)" returns \-1.
 240 .SH SEE ALSO
 241 .BR div (3),
 242 .BR fmod (3),
 243 .BR remquo (3)