xref: /freebsd/share/man/man3/Q_INI.3 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19) 
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.Dd July 8, 2018
27*5a38af1fSEdward Tomasz Napierala.Dt Q_INI 3
28*5a38af1fSEdward Tomasz Napierala.Os
29*5a38af1fSEdward Tomasz Napierala.Sh NAME
30*5a38af1fSEdward Tomasz Napierala.Nm Q_INI ,
31*5a38af1fSEdward Tomasz Napierala.Nm Q_NCBITS ,
32*5a38af1fSEdward Tomasz Napierala.Nm Q_BT ,
33*5a38af1fSEdward Tomasz Napierala.Nm Q_TC ,
34*5a38af1fSEdward Tomasz Napierala.Nm Q_NTBITS ,
35*5a38af1fSEdward Tomasz Napierala.Nm Q_NFCBITS ,
36*5a38af1fSEdward Tomasz Napierala.Nm Q_MAXNFBITS ,
37*5a38af1fSEdward Tomasz Napierala.Nm Q_NFBITS ,
38*5a38af1fSEdward Tomasz Napierala.Nm Q_NIBITS ,
39*5a38af1fSEdward Tomasz Napierala.Nm Q_RPSHFT ,
40*5a38af1fSEdward Tomasz Napierala.Nm Q_ABS ,
41*5a38af1fSEdward Tomasz Napierala.Nm Q_MAXSTRLEN ,
42*5a38af1fSEdward Tomasz Napierala.Nm Q_TOSTR ,
43*5a38af1fSEdward Tomasz Napierala.Nm Q_SHL ,
44*5a38af1fSEdward Tomasz Napierala.Nm Q_SHR ,
45*5a38af1fSEdward Tomasz Napierala.Nm Q_DEBUG
46*5a38af1fSEdward Tomasz Napierala.Nd fixed-point math miscellaneous functions/variables
47*5a38af1fSEdward Tomasz Napierala.Sh SYNOPSIS
48*5a38af1fSEdward Tomasz Napierala.In sys/qmath.h
49*5a38af1fSEdward Tomasz Napierala.Ft QTYPE
50*5a38af1fSEdward Tomasz Napierala.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft"
51*5a38af1fSEdward Tomasz Napierala.Fd Q_NCBITS
52*5a38af1fSEdward Tomasz Napierala.Ft __typeof(q)
53*5a38af1fSEdward Tomasz Napierala.Fn Q_BT "QTYPE q"
54*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
55*5a38af1fSEdward Tomasz Napierala.Fn Q_TC "QTYPE q" "ITYPE v"
56*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
57*5a38af1fSEdward Tomasz Napierala.Fn Q_NTBITS "QTYPE q"
58*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
59*5a38af1fSEdward Tomasz Napierala.Fn Q_NFCBITS "QTYPE q"
60*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
61*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXNFBITS "QTYPE q"
62*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
63*5a38af1fSEdward Tomasz Napierala.Fn Q_NFBITS "QTYPE q"
64*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
65*5a38af1fSEdward Tomasz Napierala.Fn Q_NIBITS "QTYPE q"
66*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
67*5a38af1fSEdward Tomasz Napierala.Fn Q_RPSHFT "QTYPE q"
68*5a38af1fSEdward Tomasz Napierala.Ft NTYPE
69*5a38af1fSEdward Tomasz Napierala.Fn Q_ABS "NTYPE n"
70*5a38af1fSEdward Tomasz Napierala.Ft uint32_t
71*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXSTRLEN "QTYPE q" "int base"
72*5a38af1fSEdward Tomasz Napierala.Ft char *
73*5a38af1fSEdward Tomasz Napierala.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen"
74*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
75*5a38af1fSEdward Tomasz Napierala.Fn Q_SHL "QTYPE q" "ITYPE iv"
76*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
77*5a38af1fSEdward Tomasz Napierala.Fn Q_SHR "QTYPE q" "ITYPE iv"
78*5a38af1fSEdward Tomasz Napierala.Ft char *, ...
79*5a38af1fSEdward Tomasz Napierala.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt"
80*5a38af1fSEdward Tomasz Napierala.Ft ITYPE
81*5a38af1fSEdward Tomasz Napierala.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits"
82*5a38af1fSEdward Tomasz Napierala.Sh DESCRIPTION
83*5a38af1fSEdward Tomasz Napierala.Fn Q_INI
84*5a38af1fSEdward Tomasz Napieralainitialises a Q number with the supplied integral value
85*5a38af1fSEdward Tomasz Napierala.Fa iv
86*5a38af1fSEdward Tomasz Napieralaand decimal fractional value
87*5a38af1fSEdward Tomasz Napierala.Fa dfv ,
88*5a38af1fSEdward Tomasz Napieralawith appropriate control bits based on the requested radix shift point
89*5a38af1fSEdward Tomasz Napierala.Fa rpshft .
90*5a38af1fSEdward Tomasz Napierala.Fa dfv
91*5a38af1fSEdward Tomasz Napieralamust be passed as a preprocessor literal to preserve leading zeroes.
92*5a38af1fSEdward Tomasz Napierala.Pp
93*5a38af1fSEdward Tomasz NapieralaThe
94*5a38af1fSEdward Tomasz Napierala.Dv Q_NCBITS
95*5a38af1fSEdward Tomasz Napieraladefined constant specifies the number of reserved control bits, currently 3.
96*5a38af1fSEdward Tomasz Napierala.Pp
97*5a38af1fSEdward Tomasz Napierala.Fn Q_NTBITS ,
98*5a38af1fSEdward Tomasz Napierala.Fn Q_NFCBITS ,
99*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXNFBITS ,
100*5a38af1fSEdward Tomasz Napierala.Fn Q_NFBITS
101*5a38af1fSEdward Tomasz Napieralaand
102*5a38af1fSEdward Tomasz Napierala.Fn Q_NIBITS
103*5a38af1fSEdward Tomasz Napieralareturn the
104*5a38af1fSEdward Tomasz Napierala.Fa q Ns -specific
105*5a38af1fSEdward Tomasz Napieralacount of total, control-encoded fractional, maximum fractional, effective
106*5a38af1fSEdward Tomasz Napieralafractional, and integer bits applicable to
107*5a38af1fSEdward Tomasz Napierala.Fa q
108*5a38af1fSEdward Tomasz Napieralarespectively.
109*5a38af1fSEdward Tomasz Napierala.Pp
110*5a38af1fSEdward Tomasz Napierala.Fn Q_BT
111*5a38af1fSEdward Tomasz Napieralareturns the C data type of
112*5a38af1fSEdward Tomasz Napierala.Fa q ,
113*5a38af1fSEdward Tomasz Napieralawhile
114*5a38af1fSEdward Tomasz Napierala.Fn Q_TC
115*5a38af1fSEdward Tomasz Napieralareturns
116*5a38af1fSEdward Tomasz Napierala.Fa v
117*5a38af1fSEdward Tomasz Napieralatype casted to the C data type of
118*5a38af1fSEdward Tomasz Napierala.Fa q .
119*5a38af1fSEdward Tomasz Napierala.Pp
120*5a38af1fSEdward Tomasz Napierala.Fn Q_RPSHFT
121*5a38af1fSEdward Tomasz Napieralareturns the bit position of
122*5a38af1fSEdward Tomasz Napierala.Fa q Ap s
123*5a38af1fSEdward Tomasz Napieralabinary radix point relative to bit zero.
124*5a38af1fSEdward Tomasz Napierala.Pp
125*5a38af1fSEdward Tomasz Napierala.Fn Q_ABS
126*5a38af1fSEdward Tomasz Napieralareturns the absolute value of any standard numeric type
127*5a38af1fSEdward Tomasz Napierala.Pq that uses the MSB as a sign bit, but not Q numbers
128*5a38af1fSEdward Tomasz Napieralapassed in as
129*5a38af1fSEdward Tomasz Napierala.Fa n .
130*5a38af1fSEdward Tomasz NapieralaThe function is signed/unsigned type safe.
131*5a38af1fSEdward Tomasz Napierala.Pp
132*5a38af1fSEdward Tomasz Napierala.Fn Q_SHL
133*5a38af1fSEdward Tomasz Napieralaand
134*5a38af1fSEdward Tomasz Napierala.Fn Q_SHR
135*5a38af1fSEdward Tomasz Napieralareturn the integral value
136*5a38af1fSEdward Tomasz Napierala.Fa v
137*5a38af1fSEdward Tomasz Napieralaleft or right shifted by the appropriate amount for
138*5a38af1fSEdward Tomasz Napierala.Fa q .
139*5a38af1fSEdward Tomasz Napierala.Pp
140*5a38af1fSEdward Tomasz Napierala.Fn Q_MAXSTRLEN
141*5a38af1fSEdward Tomasz Napieralacalculates the maximum number of characters that may be required to render the
142*5a38af1fSEdward Tomasz NapieralaC-string representation of
143*5a38af1fSEdward Tomasz Napierala.Fa q
144*5a38af1fSEdward Tomasz Napieralawith numeric base
145*5a38af1fSEdward Tomasz Napierala.Fa base .
146*5a38af1fSEdward Tomasz Napierala.Pp
147*5a38af1fSEdward Tomasz Napierala.Fn Q_TOSTR
148*5a38af1fSEdward Tomasz Napieralarenders the C-string representation of
149*5a38af1fSEdward Tomasz Napierala.Fa q
150*5a38af1fSEdward Tomasz Napieralawith numeric base
151*5a38af1fSEdward Tomasz Napierala.Fa base
152*5a38af1fSEdward Tomasz Napieralaand fractional precision
153*5a38af1fSEdward Tomasz Napierala.Fa prec
154*5a38af1fSEdward Tomasz Napieralainto
155*5a38af1fSEdward Tomasz Napierala.Fa s
156*5a38af1fSEdward Tomasz Napieralawhich has an available capacity of
157*5a38af1fSEdward Tomasz Napierala.Fa slen
158*5a38af1fSEdward Tomasz Napieralacharacters.
159*5a38af1fSEdward Tomasz Napierala.Fa base
160*5a38af1fSEdward Tomasz Napieralamust be in range
161*5a38af1fSEdward Tomasz Napierala.Bq 2,16 .
162*5a38af1fSEdward Tomasz NapieralaSpecifying
163*5a38af1fSEdward Tomasz Napierala.Fa prec
164*5a38af1fSEdward Tomasz Napieralaas -1 renders the number's fractional component with maximum precision.
165*5a38af1fSEdward Tomasz NapieralaIf
166*5a38af1fSEdward Tomasz Napierala.Fa slen
167*5a38af1fSEdward Tomasz Napieralais greater than zero but insufficient to hold the complete C-string, the '\\0'
168*5a38af1fSEdward Tomasz NapieralaC-string terminator will be written to
169*5a38af1fSEdward Tomasz Napierala.Fa *s ,
170*5a38af1fSEdward Tomasz Napieralathereby returning a zero length C-string.
171*5a38af1fSEdward Tomasz Napierala.Pp
172*5a38af1fSEdward Tomasz Napierala.Fn Q_DEBUG
173*5a38af1fSEdward Tomasz Napieralareturns a format string and associated data suitable for printf-like rendering
174*5a38af1fSEdward Tomasz Napieralaof debugging information pertaining to
175*5a38af1fSEdward Tomasz Napierala.Fa q .
176*5a38af1fSEdward Tomasz NapieralaIf either
177*5a38af1fSEdward Tomasz Napierala.Fa prefmt
178*5a38af1fSEdward Tomasz Napieralaand/or
179*5a38af1fSEdward Tomasz Napierala.Fa postfmt
180*5a38af1fSEdward Tomasz Napieralaare specified, they are prepended and appended to the resulting format string
181*5a38af1fSEdward Tomasz Napieralarespectively.
182*5a38af1fSEdward Tomasz NapieralaThe
183*5a38af1fSEdward Tomasz Napierala.Fa incfmt
184*5a38af1fSEdward Tomasz Napieralaboolean specifies whether to include
185*5a38af1fSEdward Tomasz Napierala.Pq Vt true
186*5a38af1fSEdward Tomasz Napieralaor exclude
187*5a38af1fSEdward Tomasz Napierala.Pq Vt false
188*5a38af1fSEdward Tomasz Napieralathe raw format string itself in the debugging output.
189*5a38af1fSEdward Tomasz Napierala.Pp
190*5a38af1fSEdward Tomasz Napierala.Fn Q_DFV2BFV
191*5a38af1fSEdward Tomasz Napieralaconverts decimal fractional value
192*5a38af1fSEdward Tomasz Napierala.Fa dfv
193*5a38af1fSEdward Tomasz Napieralato its binary-encoded representation with
194*5a38af1fSEdward Tomasz Napierala.Fa nfbits
195*5a38af1fSEdward Tomasz Napieralaof binary precision.
196*5a38af1fSEdward Tomasz Napierala.Fa dfv
197*5a38af1fSEdward Tomasz Napieralamust be passed as a preprocessor literal to preserve leading zeroes.
198*5a38af1fSEdward Tomasz NapieralaThe returned value can be used to set a Q number's fractional bits, for example
199*5a38af1fSEdward Tomasz Napieralausing
200*5a38af1fSEdward Tomasz Napierala.Fn Q_SFVAL .
201*5a38af1fSEdward Tomasz Napierala.Pp
202*5a38af1fSEdward Tomasz NapieralaAll of those functions operate on
203*5a38af1fSEdward Tomasz Napieralathe following data types:
204*5a38af1fSEdward Tomasz Napierala.Vt s8q_t ,
205*5a38af1fSEdward Tomasz Napierala.Vt u8q_t ,
206*5a38af1fSEdward Tomasz Napierala.Vt s16q_t ,
207*5a38af1fSEdward Tomasz Napierala.Vt u16q_t ,
208*5a38af1fSEdward Tomasz Napierala.Vt s32q_t ,
209*5a38af1fSEdward Tomasz Napierala.Vt u32q_t ,
210*5a38af1fSEdward Tomasz Napierala.Vt s64q_t ,
211*5a38af1fSEdward Tomasz Napieralaand
212*5a38af1fSEdward Tomasz Napierala.Vt u64q_t ,
213*5a38af1fSEdward Tomasz Napieralawhich are referred to generically as
214*5a38af1fSEdward Tomasz Napierala.Fa QTYPE .
215*5a38af1fSEdward Tomasz NapieralaThe
216*5a38af1fSEdward Tomasz Napierala.Fa ITYPE
217*5a38af1fSEdward Tomasz Napieralarefers to the
218*5a38af1fSEdward Tomasz Napierala.Xr stdint 7
219*5a38af1fSEdward Tomasz Napieralainteger types.
220*5a38af1fSEdward Tomasz Napierala.Fa NTYPE
221*5a38af1fSEdward Tomasz Napieralais used to refer to any numeric type and is therefore a superset of
222*5a38af1fSEdward Tomasz Napierala.Fa QTYPE
223*5a38af1fSEdward Tomasz Napieralaand
224*5a38af1fSEdward Tomasz Napierala.Fa ITYPE .
225*5a38af1fSEdward Tomasz Napierala.Pp
226*5a38af1fSEdward Tomasz NapieralaFor more details, see
227*5a38af1fSEdward Tomasz Napierala.Xr qmath 3 .
228*5a38af1fSEdward Tomasz Napierala.Sh RETURN VALUES
229*5a38af1fSEdward Tomasz Napierala.Fn Q_INI
230*5a38af1fSEdward Tomasz Napieralareturns the initialised Q number which can be used to chain initialise
231*5a38af1fSEdward Tomasz Napieralaadditional Q numbers.
232*5a38af1fSEdward Tomasz Napierala.Pp
233*5a38af1fSEdward Tomasz Napierala.Fn Q_TOSTR
234*5a38af1fSEdward Tomasz Napieralareturns a pointer to the '\\0' C-string terminator appended to
235*5a38af1fSEdward Tomasz Napierala.Fa s
236*5a38af1fSEdward Tomasz Napieralaafter the rendered numeric data, or NULL on buffer overflow.
237*5a38af1fSEdward Tomasz Napierala.Pp
238*5a38af1fSEdward Tomasz Napierala.Fn Q_DFV2BFV
239*5a38af1fSEdward Tomasz Napieralareturns the binary-encoded representation of decimal fractional value
240*5a38af1fSEdward Tomasz Napierala.Fa dfv
241*5a38af1fSEdward Tomasz Napieralawith
242*5a38af1fSEdward Tomasz Napierala.Fa nfbits
243*5a38af1fSEdward Tomasz Napieralaof binary precision.
244*5a38af1fSEdward Tomasz Napierala.Sh SEE ALSO
245*5a38af1fSEdward Tomasz Napierala.Xr errno 2 ,
246*5a38af1fSEdward Tomasz Napierala.Xr qmath 3 ,
247*5a38af1fSEdward Tomasz Napierala.Xr stdint 7
248*5a38af1fSEdward Tomasz Napierala.Sh HISTORY
249*5a38af1fSEdward Tomasz NapieralaThe
250*5a38af1fSEdward Tomasz Napierala.Xr qmath 3
251*5a38af1fSEdward Tomasz Napieralafunctions first appeared in
252*5a38af1fSEdward Tomasz Napierala.Fx 13.0 .
253*5a38af1fSEdward Tomasz Napierala.Sh AUTHORS
254*5a38af1fSEdward Tomasz Napierala.An -nosplit
255*5a38af1fSEdward Tomasz NapieralaThe
256*5a38af1fSEdward Tomasz Napierala.Xr qmath 3
257*5a38af1fSEdward Tomasz Napieralafunctions and this manual page were written by
258*5a38af1fSEdward Tomasz Napierala.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
259*5a38af1fSEdward Tomasz Napieralaand sponsored by Netflix, Inc.
260