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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" References consulted:
   8 .\"     Linux libc source code
   9 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  10 .\"     386BSD man pages
  11 .\"
  12 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  13 .\" Modified 2002-08-10 Walter Harms
  14 .\"     (walter.harms@informatik.uni-oldenburg.de)
  15 .\" Modified 2003-11-18, 2004-10-05 aeb
  16 .\"
  17 .TH REMAINDER 3 2022-09-09 "Linux man-pages (unreleased)"
  18 .SH NAME
  19 drem, dremf, dreml, remainder, remainderf, remainderl \- \
  20 floating-point remainder function
  21 .SH LIBRARY
  22 Math library
  23 .RI ( libm ", " \-lm )
  24 .SH SYNOPSIS
  25 .nf
  26 .B #include <math.h>
  27 .PP
  28 /* The C99 versions */
  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 .PP
  33 /* Obsolete synonyms */
  34 .BI "double drem(double " x ", double " y );
  35 .BI "float dremf(float " x ", float " y );
  36 .BI "long double dreml(long double " x ", long double " y );
  37 .fi
  38 .PP
  39 .RS -4
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .RE
  43 .PP
  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 .PP
  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 .PP
  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 .PP
  87 These functions are unaffected by the current rounding mode (see
  88 .BR fenv (3)).
  89 .PP
  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 .PP
 100 If
 101 .I x
 102 or
 103 .I y
 104 is a NaN, a NaN is returned.
 105 .PP
 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 .PP
 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 .PP
 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 .ad l
 157 .nh
 158 .TS
 159 allbox;
 160 lbx lb lb
 161 l l l.
 162 Interface       Attribute       Value
 163 T{
 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 .hy
 173 .ad
 174 .sp 1
 175 .SH STANDARDS
 176 .\" IEC 60559.
 177 The functions
 178 .BR remainder (),
 179 .BR remainderf (),
 180 and
 181 .BR remainderl ()
 182 are specified in C99, POSIX.1-2001, and POSIX.1-2008.
 183 .PP
 184 The function
 185 .BR drem ()
 186 is from 4.3BSD.
 187 The
 188 .I float
 189 and
 190 .I "long double"
 191 variants
 192 .BR dremf ()
 193 and
 194 .BR dreml ()
 195 exist on some systems, such as Tru64 and glibc2.
 196 Avoid the use of these functions in favor of
 197 .BR remainder ()
 198 etc.
 199 .SH BUGS
 200 Before glibc 2.15,
 201 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6779
 202 the call
 203 .PP
 204 .in +4n
 205 .EX
 206 remainder(nan(""), 0);
 207 .EE
 208 .in
 209 .PP
 210 returned a NaN, as expected, but wrongly caused a domain error.
 211 Since glibc 2.15, a silent NaN (i.e., no domain error) is returned.
 212 .PP
 213 Before glibc 2.15,
 214 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6783
 215 .I errno
 216 was not set to
 217 .B EDOM
 218 for the domain error that occurs when
 219 .I x
 220 is an infinity and
 221 .I y
 222 is not a NaN.
 223 .SH EXAMPLES
 224 The call "remainder(29.0, 3.0)" returns \-1.
 225 .SH SEE ALSO
 226 .BR div (3),
 227 .BR fmod (3),
 228 .BR remquo (3)