1.\" 2.\" Copyright (c) 2018 Netflix, Inc. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions, and the following disclaimer, 10.\" without modification, immediately at the beginning of the file. 11.\" 2. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 18.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 8, 2018 27.Dt Q_QADDQ 3 28.Os 29.Sh NAME 30.Nm Q_QADDQ , 31.Nm Q_QDIVQ , 32.Nm Q_QMULQ , 33.Nm Q_QSUBQ , 34.Nm Q_NORMPREC , 35.Nm Q_QMAXQ , 36.Nm Q_QMINQ , 37.Nm Q_QCLONEQ , 38.Nm Q_CPYVALQ 39.Nd fixed-point math functions which operate on two Q numbers 40.Sh SYNOPSIS 41.In sys/qmath.h 42.Ft int 43.Fn Q_QADDQ "QTYPE *a" "QTYPE b" 44.Ft int 45.Fn Q_QDIVQ "QTYPE *a" "QTYPE b" 46.Ft int 47.Fn Q_QMULQ "QTYPE *a" "QTYPE b" 48.Ft int 49.Fn Q_QSUBQ "QTYPE *a" "QTYPE b" 50.Ft int 51.Fn Q_NORMPREC "QTYPE *a" "QTYPE *b" 52.Ft QTYPE 53.Fn Q_QMAXQ "QTYPE a" "QTYPE b" 54.Ft QTYPE 55.Fn Q_QMINQ "QTYPE a" "QTYPE b" 56.Ft int 57.Fn Q_QCLONEQ "QTYPE *l" "QTYPE r" 58.Ft int 59.Fn Q_QCPYVALQ "QTYPE *l" "QTYPE r" 60.Sh DESCRIPTION 61The 62.Fn Q_QADDQ , 63.Fn Q_QDIVQ , 64.Fn Q_QMULQ , 65and 66.Fn Q_QSUBQ 67functions add, divide, multiply or subtract 68.Fa b 69to/by/from 70.Fa a 71respectively, storing the result in 72.Fa a . 73Both arguments must be initialized with the same fractional radix point. 74.Pp 75The 76.Fn Q_NORMPREC 77function attempts to normalise the precision of 78.Fa a 79and 80.Fa b 81if they differ. 82The greater of the two precisions is preferred if possible, unless that would 83truncate integer component data for the other operand, in which case the highest 84precision that preserves the integer component of both 85.Fa a 86and 87.Fa b 88is selected. 89.Pp 90The 91.Fn Q_QMAXQ 92and 93.Fn Q_QMINQ 94functions return the larger or smaller of 95.Fa a 96and 97.Fa b 98respectively. 99.Pp 100The 101.Fn Q_QCLONEQ 102and 103.Fn Q_QCPYVALQ 104functions attempt to store identical or representational copies of 105.Fa r , 106in 107.Fa l 108respectively. 109An identical Q number produced by cloning copies the control bits as well as the 110verbatim integer/fractional bits. 111A representational copy only copies the values of 112.Fa r Ap s 113integer and fractional bits, representing them in the bits available per 114.Fa l Ap s 115Q format. 116.Pp 117All of those functions operate on the following data types: 118.Vt s8q_t , 119.Vt u8q_t , 120.Vt s16q_t , 121.Vt u16q_t , 122.Vt s32q_t , 123.Vt u32q_t , 124.Vt s64q_t , 125and 126.Vt u64q_t , 127which are referred to generically as 128.Fa QTYPE . 129.Pp 130For more details, see 131.Xr qmath 3 . 132.Sh RETURN VALUES 133The 134.Fn Q_QADDQ , 135.Fn Q_QDIVQ , 136.Fn Q_QMULQ , 137.Fn Q_QSUBQ 138.Fn Q_NORMPREC , 139.Fn Q_QCLONEQ 140and 141.Fn Q_QCPYVALQ 142functions return 0 on success, or an errno on failure. 143.Er EINVAL 144is returned for divide-by-zero. 145.Er EOVERFLOW 146and 147.Er ERANGE 148are returned for overflow and underflow respectively. 149.Er ERANGE is also returned when the precision of arguments 150does not match. 151.Pp 152The 153.Fn Q_QMAXQ 154and 155.Fn Q_QMINQ 156functions return the numerically larger or smaller of their two inputs 157respectively. 158.Sh SEE ALSO 159.Xr errno 2 , 160.Xr qmath 3 , 161.Xr stdint 7 162.Sh HISTORY 163The 164.Xr qmath 3 165functions first appeared in 166.Fx 13.0 . 167.Sh AUTHORS 168.An -nosplit 169The 170.Xr qmath 3 171functions and this manual page were written by 172.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org 173and sponsored by Netflix, Inc. 174