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.\" $FreeBSD$ 27.\" 28.Dd July 8, 2018 29.Dt Q_QADDQ 3 30.Os 31.Sh NAME 32.Nm Q_QADDQ , 33.Nm Q_QDIVQ , 34.Nm Q_QMULQ , 35.Nm Q_QSUBQ , 36.Nm Q_NORMPREC , 37.Nm Q_QMAXQ , 38.Nm Q_QMINQ , 39.Nm Q_QCLONEQ , 40.Nm Q_CPYVALQ 41.Nd fixed-point math functions which operate on two Q numbers 42.Sh SYNOPSIS 43.In sys/qmath.h 44.Ft int 45.Fn Q_QADDQ "QTYPE *a" "QTYPE b" 46.Ft int 47.Fn Q_QDIVQ "QTYPE *a" "QTYPE b" 48.Ft int 49.Fn Q_QMULQ "QTYPE *a" "QTYPE b" 50.Ft int 51.Fn Q_QSUBQ "QTYPE *a" "QTYPE b" 52.Ft int 53.Fn Q_NORMPREC "QTYPE *a" "QTYPE *b" 54.Ft QTYPE 55.Fn Q_QMAXQ "QTYPE a" "QTYPE b" 56.Ft QTYPE 57.Fn Q_QMINQ "QTYPE a" "QTYPE b" 58.Ft int 59.Fn Q_QCLONEQ "QTYPE *l" "QTYPE r" 60.Ft int 61.Fn Q_QCPYVALQ "QTYPE *l" "QTYPE r" 62.Sh DESCRIPTION 63The 64.Fn Q_QADDQ , 65.Fn Q_QDIVQ , 66.Fn Q_QMULQ , 67and 68.Fn Q_QSUBQ 69functions add, divide, multiply or subtract 70.Fa b 71to/by/from 72.Fa a 73respectively, storing the result in 74.Fa a . 75Both arguments must be initialized with the same fractional radix point. 76.Pp 77The 78.Fn Q_NORMPREC 79function attempts to normalise the precision of 80.Fa a 81and 82.Fa b 83if they differ. 84The greater of the two precisions is preferred if possible, unless that would 85truncate integer component data for the other operand, in which case the highest 86precision that preserves the integer component of both 87.Fa a 88and 89.Fa b 90is selected. 91.Pp 92The 93.Fn Q_QMAXQ 94and 95.Fn Q_QMINQ 96functions return the larger or smaller of 97.Fa a 98and 99.Fa b 100respectively. 101.Pp 102The 103.Fn Q_QCLONEQ 104and 105.Fn Q_QCPYVALQ 106functions attempt to store identical or representational copies of 107.Fa r , 108in 109.Fa l 110respectively. 111An identical Q number produced by cloning copies the control bits as well as the 112verbatim integer/fractional bits. 113A representational copy only copies the values of 114.Fa r Ap s 115integer and fractional bits, representing them in the bits available per 116.Fa l Ap s 117Q format. 118.Pp 119All of those functions operate on the following data types: 120.Vt s8q_t , 121.Vt u8q_t , 122.Vt s16q_t , 123.Vt u16q_t , 124.Vt s32q_t , 125.Vt u32q_t , 126.Vt s64q_t , 127and 128.Vt u64q_t , 129which are referred to generically as 130.Fa QTYPE . 131.Pp 132For more details, see 133.Xr qmath 3 . 134.Sh RETURN VALUES 135The 136.Fn Q_QADDQ , 137.Fn Q_QDIVQ , 138.Fn Q_QMULQ , 139.Fn Q_QSUBQ 140.Fn Q_NORMPREC , 141.Fn Q_QCLONEQ 142and 143.Fn Q_QCPYVALQ 144functions return 0 on success, or an errno on failure. 145.Er EINVAL 146is returned for divide-by-zero. 147.Er EOVERFLOW 148and 149.Er ERANGE 150are returned for overflow and underflow respectively. 151.Er ERANGE is also returned when the precision of arguments 152does not match. 153.Pp 154The 155.Fn Q_QMAXQ 156and 157.Fn Q_QMINQ 158functions return the numerically larger or smaller of their two inputs 159respectively. 160.Sh SEE ALSO 161.Xr errno 2 , 162.Xr qmath 3 , 163.Xr stdint 7 164.Sh HISTORY 165The 166.Xr qmath 3 167functions first appeared in 168.Fx 13.0 . 169.Sh AUTHORS 170.An -nosplit 171The 172.Xr qmath 3 173functions and this manual page were written by 174.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org 175and sponsored by Netflix, Inc. 176