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