1.\" $NetBSD: remainder.3,v 1.3 2024/01/26 19:27:30 nros Exp $ 2.\" 3.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd January 24, 2024 28.Dt REMAINDER 3 29.Os 30.Sh NAME 31.Nm remainder , 32.Nm remainderf , 33.Nm remainderl , 34.Nm remquo , 35.Nm remquof , 36.Nm remquol 37.Nd remainder functions 38.Sh LIBRARY 39.Lb libm 40.Sh SYNOPSIS 41.In math.h 42.Ft double 43.Fn remainder "double x" "double y" 44.Ft float 45.Fn remainderf "float x" "float y" 46.Ft long double 47.Fn remainderl "long double x" "long double y" 48.Ft double 49.Fn remquo "double x" "double y" "int *quo" 50.Ft float 51.Fn remquof "float x" "float y" "int *quo" 52.Ft long double 53.Fn remquol "long double x" "long double y" "int *quo" 54.Sh DESCRIPTION 55Provided that 56.Fa y 57\*(Ne 0 , 58the 59.Fn remainder 60.Fn remainderf 61and 62.Fn remainderl 63functions calculate the floating-point remainder 64.Fa r 65of 66.Bd -ragged -offset indent 67.Va r 68= 69.Va x - ny , 70.Ed 71.Pp 72where 73.Fa n 74is the integral value nearest to the exact value of 75.Fa x 76/ 77.Fa y . 78If 79.Bd -ragged -offset indent 80.Va | n 81- 82.Va x / y | 83= 1/2 , 84.Ed 85.Pp 86the value 87.Fa n 88is chosen to be even. 89Consequently, the remainder is computed exactly and 90.Va | r | 91\*(Le 92.Fa | y | 93/ 2 . 94.Pp 95Also the 96.Fn remquo 97.Fn remquof 98and 99.Fn remquol 100functions calculate the remainder as described above. 101But these additionally use 102.Fa quo 103to store a value whose sign is the sign of 104.Va x / y 105and whose magnitude is congruent modulo 106.Va 2^k 107to the magnitude of the integral quotient of 108.Va x / y , 109where 110.Fa k 111is an implementation-defined integer greater than or equal to 3. 112.Pp 113The rationale of the 114.Fn remquo 115family of functions relates to situations where 116only few bits of the quotient are required. 117The exact representation of the quotient may not be meaningful when 118.Fa x 119is large in magnitude compared to 120.Fa y . 121.Sh RETURN VALUES 122The functions return the remainder independent of the rounding mode. 123If 124.Fa y 125is zero , 126\*(Na 127is returned and a domain error occurs. 128A domain error occurs and a 129\*(Na 130is returned also when 131.Fa x 132is infinite but 133.Fa y 134is not a 135\*(Na. 136If either 137.Fa x 138or 139.Fa y 140is 141\*(Na, 142a 143\*(Na 144is always returned. 145.Sh SEE ALSO 146.Xr div 3 , 147.Xr fast_remainder32 3 , 148.Xr fmod 3 , 149.Xr math 3 150.Sh STANDARDS 151The described functions conform to 152.St -isoC-99 . 153