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 2015-04-19 "" "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 .sp
  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 .sp
  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 .sp
  55 .fi
  56 Link with \fI\-lm\fP.
  57 .sp
  58 .in -4n
  59 Feature Test Macro Requirements for glibc (see
  60 .BR feature_test_macros (7)):
  61 .in
  62 .sp
  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 .br
  72 or
  73 .I cc\ -std=c99
  74 .RE
  75 .br
  76 .BR remainderf (),
  77 .BR remainderl ():
  78 .RS 4
  79 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  80     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  81     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  82 .br
  83 or
  84 .I cc\ -std=c99
  85 .RE
  86 .br
  87 .BR drem (),
  88 .BR dremf (),
  89 .BR dreml ():
  90 .RS 4
  91 /* Since glibc 2.19: */ _DEFAULT_SOURCE
  92     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  93 .RE
  94 .ad b
  95 .SH DESCRIPTION
  96 These
  97 functions compute the remainder of dividing
  98 .I x
  99 by
 100 .IR y .
 101 The return value is
 102 \fIx\fP\-\fIn\fP*\fIy\fP,
 103 where
 104 .I n
 105 is the value
 106 .IR "x\ /\ y" ,
 107 rounded to the nearest integer.
 108 If the absolute value of
 109 \fIx\fP\-\fIn\fP*\fIy\fP
 110 is 0.5,
 111 .I n
 112 is chosen to be even.
 113
 114 These functions are unaffected by the current rounding mode (see
 115 .BR fenv (3)).
 116 .LP
 117 The
 118 .BR drem ()
 119 function does precisely the same thing.
 120 .SH RETURN VALUE
 121 On success, these
 122 functions return the floating-point remainder,
 123 \fIx\fP\-\fIn\fP*\fIy\fP.
 124 If the return value is 0, it has the sign of
 125 .IR x .
 126
 127 If
 128 .I x
 129 or
 130 .I y
 131 is a NaN, a NaN is returned.
 132
 133 If
 134 .I x
 135 is an infinity,
 136 and
 137 .I y
 138 is not a NaN,
 139 a domain error occurs, and
 140 a NaN is returned.
 141
 142 If
 143 .I y
 144 is zero,
 145 .\" FIXME . Instead, glibc gives a domain error even if x is a NaN
 146 and
 147 .I x
 148 is not a NaN,
 149 .\" Interestingly, remquo(3) does not have the same problem.
 150 a domain error occurs, and
 151 a NaN is returned.
 152 .SH ERRORS
 153 See
 154 .BR math_error (7)
 155 for information on how to determine whether an error has occurred
 156 when calling these functions.
 157 .PP
 158 The following errors can occur:
 159 .TP
 160 Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN
 161 .\" .I errno
 162 .\" is set to
 163 .\" .BR EDOM .
 164 An invalid floating-point exception
 165 .RB ( FE_INVALID )
 166 is raised.
 167 .IP
 168 These functions do not set
 169 .IR errno
 170 for this case.
 171 .\" FIXME . Is it intentional that these functions do not set errno?
 172 .\" They do set errno for the y == 0 case, below.
 173 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783
 174 .TP
 175 Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN
 176 .I errno
 177 is set to
 178 .BR EDOM .
 179 An invalid floating-point exception
 180 .RB ( FE_INVALID )
 181 is raised.
 182 .SH ATTRIBUTES
 183 For an explanation of the terms used in this section, see
 184 .BR attributes (7).
 185 .TS
 186 allbox;
 187 lbw26 lb lb
 188 l l l.
 189 Interface       Attribute       Value
 190 T{
 191 .BR drem (),
 192 .BR dremf (),
 193 .BR dreml (),
 194 .br
 195 .BR remainder (),
 196 .BR remainderf (),
 197 .br
 198 .BR remainderl ()
 199 T}      Thread safety   MT-Safe
 200 .TE
 201 .SH CONFORMING TO
 202 .\" IEC 60559.
 203 The functions
 204 .BR remainder (),
 205 .BR remainderf (),
 206 and
 207 .BR remainderl ()
 208 are specified in C99, POSIX.1-2001, and POSIX.1-2008.
 209
 210 The function
 211 .BR drem ()
 212 is from 4.3BSD.
 213 The
 214 .I float
 215 and
 216 .I "long double"
 217 variants
 218 .BR dremf ()
 219 and
 220 .BR dreml ()
 221 exist on some systems, such as Tru64 and glibc2.
 222 Avoid the use of these functions in favor of
 223 .BR remainder ()
 224 etc.
 225 .SH BUGS
 226 The call
 227
 228     remainder(nan(""), 0);
 229
 230 returns a NaN, as expected, but wrongly causes a domain error;
 231 it should yield a silent NaN.
 232 .\" FIXME . this bug occurs as at glibc 2.8.
 233 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779
 234 .SH EXAMPLE
 235 The call "remainder(29.0, 3.0)" returns \-1.
 236 .SH SEE ALSO
 237 .BR div (3),
 238 .BR fmod (3),
 239 .BR remquo (3)