xref: /freebsd/share/man/man3/Q_INI.3 (revision 5a38af1fb8982572bce298bcdeeb875925e00ab0) 
1*5a38af1fSEdward Tomasz Napierala.\"
2*5a38af1fSEdward Tomasz Napierala.\" Copyright (c) 2018 Netflix, Inc.
3*5a38af1fSEdward Tomasz Napierala.\" All rights reserved.
4*5a38af1fSEdward Tomasz Napierala.\"
5*5a38af1fSEdward Tomasz Napierala.\" Redistribution and use in source and binary forms, with or without
6*5a38af1fSEdward Tomasz Napierala.\" modification, are permitted provided that the following conditions
7*5a38af1fSEdward Tomasz Napierala.\" are met:
8*5a38af1fSEdward Tomasz Napierala.\" 1. Redistributions of source code must retain the above copyright
9*5a38af1fSEdward Tomasz Napierala.\"    notice, this list of conditions, and the following disclaimer,
10*5a38af1fSEdward Tomasz Napierala.\"    without modification, immediately at the beginning of the file.
11*5a38af1fSEdward Tomasz Napierala.\" 2. The name of the author may not be used to endorse or promote products
12*5a38af1fSEdward Tomasz Napierala.\"    derived from this software without specific prior written permission.
13*5a38af1fSEdward Tomasz Napierala.\"
14*5a38af1fSEdward Tomasz Napierala.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15*5a38af1fSEdward Tomasz Napierala.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16*5a38af1fSEdward Tomasz Napierala.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17*5a38af1fSEdward Tomasz Napierala.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
18*5a38af1fSEdward Tomasz Napierala.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19*5a38af1fSEdward Tomasz Napierala.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20*5a38af1fSEdward Tomasz Napierala.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21*5a38af1fSEdward Tomasz Napierala.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22*5a38af1fSEdward Tomasz Napierala.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23*5a38af1fSEdward Tomasz Napierala.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24*5a38af1fSEdward Tomasz Napierala.\" SUCH DAMAGE.
25*5a38af1fSEdward Tomasz Napierala.\"
26*5a38af1fSEdward Tomasz Napierala.\" $FreeBSD$
27*5a38af1fSEdward Tomasz Napierala.\"
28*5a38af1fSEdward Tomasz Napierala.Dd July 8, 2018
29*5a38af1fSEdward Tomasz Napierala.Dt Q_INI 3
30*5a38af1fSEdward Tomasz Napierala.Os
31*5a38af1fSEdward Tomasz Napierala.Sh NAME
32*5a38af1fSEdward Tomasz Napierala.Nm Q_INI ,
33*5a38af1fSEdward Tomasz Napierala.Nm Q_NCBITS ,
34*5a38af1fSEdward Tomasz Napierala.Nm Q_BT ,
35*5a38af1fSEdward Tomasz Napierala.Nm Q_TC ,
36*5a38af1fSEdward Tomasz Napierala.Nm Q_NTBITS ,
37*5a38af1fSEdward Tomasz Napierala.Nm Q_NFCBITS ,
38*5a38af1fSEdward Tomasz Napierala.Nm Q_MAXNFBITS ,
39*5a38af1fSEdward Tomasz Napierala.Nm Q_NFBITS ,
40*5a38af1fSEdward Tomasz Napierala.Nm Q_NIBITS ,
41*5a38af1fSEdward Tomasz Napierala.Nm Q_RPSHFT ,
42*5a38af1fSEdward Tomasz Napierala.Nm Q_ABS ,
43*5a38af1fSEdward Tomasz Napierala.Nm Q_MAXSTRLEN ,
44*5a38af1fSEdward Tomasz Napierala.Nm Q_TOSTR ,
45*5a38af1fSEdward Tomasz Napierala.Nm Q_SHL ,
46*5a38af1fSEdward Tomasz Napierala.Nm Q_SHR ,
47*5a38af1fSEdward Tomasz Napierala.Nm Q_DEBUG
48*5a38af1fSEdward Tomasz Napierala.Nd fixed-point math miscellaneous functions/variables
49*5a38af1fSEdward Tomasz Napierala.Sh SYNOPSIS
50*5a38af1fSEdward Tomasz Napierala.In sys/qmath.h
51*5a38af1fSEdward Tomasz Napierala.Ft QTYPE
52*5a38af1fSEdward Tomasz Napierala.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft"
53*5a38af1fSEdward Tomasz Napierala.Fd Q_NCBITS
54*5a38af1fSEdward Tomasz Napierala.Ft __typeof(q)
55*5a38af1fSEdward Tomasz Napierala.Fn Q_BT "QTYPE q"
56*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
57*5a38af1fSEdward Tomasz Napierala.Fn Q_TC "QTYPE q" "ITYPE v"
58*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
59*5a38af1fSEdward Tomasz Napierala.Fn Q_NTBITS "QTYPE q"
60*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
61*5a38af1fSEdward Tomasz Napierala.Fn Q_NFCBITS "QTYPE q"
62*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
63*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXNFBITS "QTYPE q"
64*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
65*5a38af1fSEdward Tomasz Napierala.Fn Q_NFBITS "QTYPE q"
66*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
67*5a38af1fSEdward Tomasz Napierala.Fn Q_NIBITS "QTYPE q"
68*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
69*5a38af1fSEdward Tomasz Napierala.Fn Q_RPSHFT "QTYPE q"
70*5a38af1fSEdward Tomasz Napierala.Ft NTYPE
71*5a38af1fSEdward Tomasz Napierala.Fn Q_ABS "NTYPE n"
72*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
73*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXSTRLEN "QTYPE q" "int base"
74*5a38af1fSEdward Tomasz Napierala.Ft char *
75*5a38af1fSEdward Tomasz Napierala.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen"
76*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
77*5a38af1fSEdward Tomasz Napierala.Fn Q_SHL "QTYPE q" "ITYPE iv"
78*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
79*5a38af1fSEdward Tomasz Napierala.Fn Q_SHR "QTYPE q" "ITYPE iv"
80*5a38af1fSEdward Tomasz Napierala.Ft char *, ...
81*5a38af1fSEdward Tomasz Napierala.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt"
82*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
83*5a38af1fSEdward Tomasz Napierala.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits"
84*5a38af1fSEdward Tomasz Napierala.Sh DESCRIPTION
85*5a38af1fSEdward Tomasz Napierala.Fn Q_INI
86*5a38af1fSEdward Tomasz Napieralainitialises a Q number with the supplied integral value
87*5a38af1fSEdward Tomasz Napierala.Fa iv
88*5a38af1fSEdward Tomasz Napieralaand decimal fractional value
89*5a38af1fSEdward Tomasz Napierala.Fa dfv ,
90*5a38af1fSEdward Tomasz Napieralawith appropriate control bits based on the requested radix shift point
91*5a38af1fSEdward Tomasz Napierala.Fa rpshft .
92*5a38af1fSEdward Tomasz Napierala.Fa dfv
93*5a38af1fSEdward Tomasz Napieralamust be passed as a preprocessor literal to preserve leading zeroes.
94*5a38af1fSEdward Tomasz Napierala.Pp
95*5a38af1fSEdward Tomasz NapieralaThe
96*5a38af1fSEdward Tomasz Napierala.Dv Q_NCBITS
97*5a38af1fSEdward Tomasz Napieraladefined constant specifies the number of reserved control bits, currently 3.
98*5a38af1fSEdward Tomasz Napierala.Pp
99*5a38af1fSEdward Tomasz Napierala.Fn Q_NTBITS ,
100*5a38af1fSEdward Tomasz Napierala.Fn Q_NFCBITS ,
101*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXNFBITS ,
102*5a38af1fSEdward Tomasz Napierala.Fn Q_NFBITS
103*5a38af1fSEdward Tomasz Napieralaand
104*5a38af1fSEdward Tomasz Napierala.Fn Q_NIBITS
105*5a38af1fSEdward Tomasz Napieralareturn the
106*5a38af1fSEdward Tomasz Napierala.Fa q Ns -specific
107*5a38af1fSEdward Tomasz Napieralacount of total, control-encoded fractional, maximum fractional, effective
108*5a38af1fSEdward Tomasz Napieralafractional, and integer bits applicable to
109*5a38af1fSEdward Tomasz Napierala.Fa q
110*5a38af1fSEdward Tomasz Napieralarespectively.
111*5a38af1fSEdward Tomasz Napierala.Pp
112*5a38af1fSEdward Tomasz Napierala.Fn Q_BT
113*5a38af1fSEdward Tomasz Napieralareturns the C data type of
114*5a38af1fSEdward Tomasz Napierala.Fa q ,
115*5a38af1fSEdward Tomasz Napieralawhile
116*5a38af1fSEdward Tomasz Napierala.Fn Q_TC
117*5a38af1fSEdward Tomasz Napieralareturns
118*5a38af1fSEdward Tomasz Napierala.Fa v
119*5a38af1fSEdward Tomasz Napieralatype casted to the C data type of
120*5a38af1fSEdward Tomasz Napierala.Fa q .
121*5a38af1fSEdward Tomasz Napierala.Pp
122*5a38af1fSEdward Tomasz Napierala.Fn Q_RPSHFT
123*5a38af1fSEdward Tomasz Napieralareturns the bit position of
124*5a38af1fSEdward Tomasz Napierala.Fa q Ap s
125*5a38af1fSEdward Tomasz Napieralabinary radix point relative to bit zero.
126*5a38af1fSEdward Tomasz Napierala.Pp
127*5a38af1fSEdward Tomasz Napierala.Fn Q_ABS
128*5a38af1fSEdward Tomasz Napieralareturns the absolute value of any standard numeric type
129*5a38af1fSEdward Tomasz Napierala.Pq that uses the MSB as a sign bit, but not Q numbers
130*5a38af1fSEdward Tomasz Napieralapassed in as
131*5a38af1fSEdward Tomasz Napierala.Fa n .
132*5a38af1fSEdward Tomasz NapieralaThe function is signed/unsigned type safe.
133*5a38af1fSEdward Tomasz Napierala.Pp
134*5a38af1fSEdward Tomasz Napierala.Fn Q_SHL
135*5a38af1fSEdward Tomasz Napieralaand
136*5a38af1fSEdward Tomasz Napierala.Fn Q_SHR
137*5a38af1fSEdward Tomasz Napieralareturn the integral value
138*5a38af1fSEdward Tomasz Napierala.Fa v
139*5a38af1fSEdward Tomasz Napieralaleft or right shifted by the appropriate amount for
140*5a38af1fSEdward Tomasz Napierala.Fa q .
141*5a38af1fSEdward Tomasz Napierala.Pp
142*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXSTRLEN
143*5a38af1fSEdward Tomasz Napieralacalculates the maximum number of characters that may be required to render the
144*5a38af1fSEdward Tomasz NapieralaC-string representation of
145*5a38af1fSEdward Tomasz Napierala.Fa q
146*5a38af1fSEdward Tomasz Napieralawith numeric base
147*5a38af1fSEdward Tomasz Napierala.Fa base .
148*5a38af1fSEdward Tomasz Napierala.Pp
149*5a38af1fSEdward Tomasz Napierala.Fn Q_TOSTR
150*5a38af1fSEdward Tomasz Napieralarenders the C-string representation of
151*5a38af1fSEdward Tomasz Napierala.Fa q
152*5a38af1fSEdward Tomasz Napieralawith numeric base
153*5a38af1fSEdward Tomasz Napierala.Fa base
154*5a38af1fSEdward Tomasz Napieralaand fractional precision
155*5a38af1fSEdward Tomasz Napierala.Fa prec
156*5a38af1fSEdward Tomasz Napieralainto
157*5a38af1fSEdward Tomasz Napierala.Fa s
158*5a38af1fSEdward Tomasz Napieralawhich has an available capacity of
159*5a38af1fSEdward Tomasz Napierala.Fa slen
160*5a38af1fSEdward Tomasz Napieralacharacters.
161*5a38af1fSEdward Tomasz Napierala.Fa base
162*5a38af1fSEdward Tomasz Napieralamust be in range
163*5a38af1fSEdward Tomasz Napierala.Bq 2,16 .
164*5a38af1fSEdward Tomasz NapieralaSpecifying
165*5a38af1fSEdward Tomasz Napierala.Fa prec
166*5a38af1fSEdward Tomasz Napieralaas -1 renders the number's fractional component with maximum precision.
167*5a38af1fSEdward Tomasz NapieralaIf
168*5a38af1fSEdward Tomasz Napierala.Fa slen
169*5a38af1fSEdward Tomasz Napieralais greater than zero but insufficient to hold the complete C-string, the '\\0'
170*5a38af1fSEdward Tomasz NapieralaC-string terminator will be written to
171*5a38af1fSEdward Tomasz Napierala.Fa *s ,
172*5a38af1fSEdward Tomasz Napieralathereby returning a zero length C-string.
173*5a38af1fSEdward Tomasz Napierala.Pp
174*5a38af1fSEdward Tomasz Napierala.Fn Q_DEBUG
175*5a38af1fSEdward Tomasz Napieralareturns a format string and associated data suitable for printf-like rendering
176*5a38af1fSEdward Tomasz Napieralaof debugging information pertaining to
177*5a38af1fSEdward Tomasz Napierala.Fa q .
178*5a38af1fSEdward Tomasz NapieralaIf either
179*5a38af1fSEdward Tomasz Napierala.Fa prefmt
180*5a38af1fSEdward Tomasz Napieralaand/or
181*5a38af1fSEdward Tomasz Napierala.Fa postfmt
182*5a38af1fSEdward Tomasz Napieralaare specified, they are prepended and appended to the resulting format string
183*5a38af1fSEdward Tomasz Napieralarespectively.
184*5a38af1fSEdward Tomasz NapieralaThe
185*5a38af1fSEdward Tomasz Napierala.Fa incfmt
186*5a38af1fSEdward Tomasz Napieralaboolean specifies whether to include
187*5a38af1fSEdward Tomasz Napierala.Pq Vt true
188*5a38af1fSEdward Tomasz Napieralaor exclude
189*5a38af1fSEdward Tomasz Napierala.Pq Vt false
190*5a38af1fSEdward Tomasz Napieralathe raw format string itself in the debugging output.
191*5a38af1fSEdward Tomasz Napierala.Pp
192*5a38af1fSEdward Tomasz Napierala.Fn Q_DFV2BFV
193*5a38af1fSEdward Tomasz Napieralaconverts decimal fractional value
194*5a38af1fSEdward Tomasz Napierala.Fa dfv
195*5a38af1fSEdward Tomasz Napieralato its binary-encoded representation with
196*5a38af1fSEdward Tomasz Napierala.Fa nfbits
197*5a38af1fSEdward Tomasz Napieralaof binary precision.
198*5a38af1fSEdward Tomasz Napierala.Fa dfv
199*5a38af1fSEdward Tomasz Napieralamust be passed as a preprocessor literal to preserve leading zeroes.
200*5a38af1fSEdward Tomasz NapieralaThe returned value can be used to set a Q number's fractional bits, for example
201*5a38af1fSEdward Tomasz Napieralausing
202*5a38af1fSEdward Tomasz Napierala.Fn Q_SFVAL .
203*5a38af1fSEdward Tomasz Napierala.Pp
204*5a38af1fSEdward Tomasz NapieralaAll of those functions operate on
205*5a38af1fSEdward Tomasz Napieralathe following data types:
206*5a38af1fSEdward Tomasz Napierala.Vt s8q_t ,
207*5a38af1fSEdward Tomasz Napierala.Vt u8q_t ,
208*5a38af1fSEdward Tomasz Napierala.Vt s16q_t ,
209*5a38af1fSEdward Tomasz Napierala.Vt u16q_t ,
210*5a38af1fSEdward Tomasz Napierala.Vt s32q_t ,
211*5a38af1fSEdward Tomasz Napierala.Vt u32q_t ,
212*5a38af1fSEdward Tomasz Napierala.Vt s64q_t ,
213*5a38af1fSEdward Tomasz Napieralaand
214*5a38af1fSEdward Tomasz Napierala.Vt u64q_t ,
215*5a38af1fSEdward Tomasz Napieralawhich are referred to generically as
216*5a38af1fSEdward Tomasz Napierala.Fa QTYPE .
217*5a38af1fSEdward Tomasz NapieralaThe
218*5a38af1fSEdward Tomasz Napierala.Fa ITYPE
219*5a38af1fSEdward Tomasz Napieralarefers to the
220*5a38af1fSEdward Tomasz Napierala.Xr stdint 7
221*5a38af1fSEdward Tomasz Napieralainteger types.
222*5a38af1fSEdward Tomasz Napierala.Fa NTYPE
223*5a38af1fSEdward Tomasz Napieralais used to refer to any numeric type and is therefore a superset of
224*5a38af1fSEdward Tomasz Napierala.Fa QTYPE
225*5a38af1fSEdward Tomasz Napieralaand
226*5a38af1fSEdward Tomasz Napierala.Fa ITYPE .
227*5a38af1fSEdward Tomasz Napierala.Pp
228*5a38af1fSEdward Tomasz NapieralaFor more details, see
229*5a38af1fSEdward Tomasz Napierala.Xr qmath 3 .
230*5a38af1fSEdward Tomasz Napierala.Sh RETURN VALUES
231*5a38af1fSEdward Tomasz Napierala.Fn Q_INI
232*5a38af1fSEdward Tomasz Napieralareturns the initialised Q number which can be used to chain initialise
233*5a38af1fSEdward Tomasz Napieralaadditional Q numbers.
234*5a38af1fSEdward Tomasz Napierala.Pp
235*5a38af1fSEdward Tomasz Napierala.Fn Q_TOSTR
236*5a38af1fSEdward Tomasz Napieralareturns a pointer to the '\\0' C-string terminator appended to
237*5a38af1fSEdward Tomasz Napierala.Fa s
238*5a38af1fSEdward Tomasz Napieralaafter the rendered numeric data, or NULL on buffer overflow.
239*5a38af1fSEdward Tomasz Napierala.Pp
240*5a38af1fSEdward Tomasz Napierala.Fn Q_DFV2BFV
241*5a38af1fSEdward Tomasz Napieralareturns the binary-encoded representation of decimal fractional value
242*5a38af1fSEdward Tomasz Napierala.Fa dfv
243*5a38af1fSEdward Tomasz Napieralawith
244*5a38af1fSEdward Tomasz Napierala.Fa nfbits
245*5a38af1fSEdward Tomasz Napieralaof binary precision.
246*5a38af1fSEdward Tomasz Napierala.Sh SEE ALSO
247*5a38af1fSEdward Tomasz Napierala.Xr errno 2 ,
248*5a38af1fSEdward Tomasz Napierala.Xr qmath 3 ,
249*5a38af1fSEdward Tomasz Napierala.Xr stdint 7
250*5a38af1fSEdward Tomasz Napierala.Sh HISTORY
251*5a38af1fSEdward Tomasz NapieralaThe
252*5a38af1fSEdward Tomasz Napierala.Xr qmath 3
253*5a38af1fSEdward Tomasz Napieralafunctions first appeared in
254*5a38af1fSEdward Tomasz Napierala.Fx 13.0 .
255*5a38af1fSEdward Tomasz Napierala.Sh AUTHORS
256*5a38af1fSEdward Tomasz Napierala.An -nosplit
257*5a38af1fSEdward Tomasz NapieralaThe
258*5a38af1fSEdward Tomasz Napierala.Xr qmath 3
259*5a38af1fSEdward Tomasz Napieralafunctions and this manual page were written by
260*5a38af1fSEdward Tomasz Napierala.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
261*5a38af1fSEdward Tomasz Napieralaand sponsored by Netflix, Inc.
262