share/man/man3/Q_QADDI.3

   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_QADDI 3
  30 .Os
  31 .Sh NAME
  32 .Nm Q_QADDI ,
  33 .Nm Q_QDIVI ,
  34 .Nm Q_QMULI ,
  35 .Nm Q_QSUBI ,
  36 .Nm Q_QFRACI ,
  37 .Nm Q_QCPYVALI
  38 .Nd fixed-point math functions which apply integers to a Q number
  39 .Sh SYNOPSIS
  40 .In sys/qmath.h
  41 .Ft int
  42 .Fn Q_QADDI "QTYPE *a" "ITYPE b"
  43 .Ft int
  44 .Fn Q_QDIVI "QTYPE *a" "ITYPE b"
  45 .Ft int
  46 .Fn Q_QMULI "QTYPE *a" "ITYPE b"
  47 .Ft int
  48 .Fn Q_QSUBI "QTYPE *a" "ITYPE b"
  49 .Ft int
  50 .Fn Q_QFRACI "QTYPE *q" "ITYPE n" "ITYPE d"
  51 .Ft int
  52 .Fn Q_QCPYVALI "QTYPE *q" "ITYPE i"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn Q_QADDI ,
  56 .Fn Q_QDIVI ,
  57 .Fn Q_QMULI
  58 and
  59 .Fn Q_QSUBI
  60 functions add, divide, multiply or subtract
  61 .Fa b
  62 to/by/from
  63 .Fa a
  64 respectively, storing the result in
  65 .Fa a .
  66 .Pp
  67 The
  68 .Fn Q_QFRACI
  69 function computes the fraction
  70 .Fa n
  71 divided by
  72 .Fa d
  73 and stores the fixed-point result in
  74 .Fa q .
  75 .Pp
  76 The
  77 .Fn Q_QCPYVALI
  78 function overwrites
  79 .Fa q Ap s
  80 integer and fractional bits with the Q representation of integer value
  81 .Fa i .
  82 .Pp
  83 All of those functions operate on
  84 the following data types:
  85 .Vt s8q_t ,
  86 .Vt u8q_t ,
  87 .Vt s16q_t ,
  88 .Vt u16q_t ,
  89 .Vt s32q_t ,
  90 .Vt u32q_t ,
  91 .Vt s64q_t ,
  92 and
  93 .Vt u64q_t ,
  94 which are referred to generically as
  95 .Fa QTYPE .
  96 The
  97 .Fa ITYPE
  98 refers to the
  99 .Xr stdint 7
 100 integer types.
 101 .Pp
 102 For more details, see
 103 .Xr qmath 3 .
 104 .Sh RETURN VALUES
 105 .Fn Q_QADDI ,
 106 .Fn Q_QDIVI ,
 107 .Fn Q_QMULI ,
 108 .Fn Q_QSUBI ,
 109 .Fn Q_QFRACI
 110 and
 111 .Fn Q_QCPYVALI
 112 functions return 0 on success, or an errno on failure.
 113 .Er EINVAL
 114 is returned for divide-by-zero.
 115 .Er EOVERFLOW
 116 and
 117 .Er ERANGE
 118 are returned for overflow and underflow respectively.
 119 .Sh SEE ALSO
 120 .Xr errno 2 ,
 121 .Xr qmath 3 ,
 122 .Xr stdint 7
 123 .Sh HISTORY
 124 The
 125 .Xr qmath 3
 126 functions first appeared in
 127 .Fx 13.0 .
 128 .Sh AUTHORS
 129 .An -nosplit
 130 The
 131 .Xr qmath 3
 132 functions and this manual page were written by
 133 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
 134 and sponsored by Netflix, Inc.