---
name: "Q_SHL"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/Q_ABS"
---

# Q\_SHL(3)

fixed-point math miscellaneous functions/variables

Part of [Q\_ABS(3)](/Q_ABS/3.md).

## NAME

**Q\_INI**, **Q\_NCBITS**, **Q\_BT**, **Q\_TC**, **Q\_NTBITS**, **Q\_NFCBITS**, **Q\_MAXNFBITS**, **Q\_NFBITS**, **Q\_NIBITS**, **Q\_RPSHFT**, **Q\_ABS**, **Q\_MAXSTRLEN**, **Q\_TOSTR**, **Q\_SHL**, **Q\_SHR**, **Q\_DEBUG** – fixed-point math miscellaneous functions/variables

## SYNOPSIS

**#include \<sys/qmath.h\>**

*QTYPE*\

**Q\_INI**(*QTYPE \*q*, *ITYPE iv*, *ITYPE dfv*, *int rpshft*);

**Q\_NCBITS**

*\_\_typeof(q)*\

**Q\_BT**(*QTYPE q*);

*ITYPE*\

**Q\_TC**(*QTYPE q*, *ITYPE v*);

*uint32\_t*\

**Q\_NTBITS**(*QTYPE q*);

*uint32\_t*\

**Q\_NFCBITS**(*QTYPE q*);

*uint32\_t*\

**Q\_MAXNFBITS**(*QTYPE q*);

*uint32\_t*\

**Q\_NFBITS**(*QTYPE q*);

*uint32\_t*\

**Q\_NIBITS**(*QTYPE q*);

*uint32\_t*\

**Q\_RPSHFT**(*QTYPE q*);

*NTYPE*\

**Q\_ABS**(*NTYPE n*);

*uint32\_t*\

**Q\_MAXSTRLEN**(*QTYPE q*, *int base*);

*char* *\**\

**Q\_TOSTR**(*QTYPE q*, *int prec*, *int base*, *char \*s*, *int slen*);

*ITYPE*\

**Q\_SHL**(*QTYPE q*, *ITYPE iv*);

*ITYPE*\

**Q\_SHR**(*QTYPE q*, *ITYPE iv*);

*char* *\*,* *...*\

**Q\_DEBUG**(*QTYPE q*, *char \*prefmt*, *char \*postfmt*, *incfmt*);

*ITYPE*\

**Q\_DFV2BFV**(*ITYPE dfv*, *int nfbits*);

## DESCRIPTION

**Q\_INI**() initialises a Q number with the supplied integral value *iv* and decimal fractional value *dfv*, with appropriate control bits based on the requested radix shift point *rpshft*. *dfv* must be passed as a preprocessor literal to preserve leading zeroes.

The Q\_NCBITS defined constant specifies the number of reserved control bits, currently 3.

**Q\_NTBITS**(), **Q\_NFCBITS**(), **Q\_MAXNFBITS**(), **Q\_NFBITS**() and **Q\_NIBITS**() return the *q*-specific count of total, control-encoded fractional, maximum fractional, effective fractional, and integer bits applicable to *q* respectively.

**Q\_BT**() returns the C data type of *q*, while **Q\_TC**() returns *v* type casted to the C data type of *q*.

**Q\_RPSHFT**() returns the bit position of *q*'s binary radix point relative to bit zero.

**Q\_ABS**() returns the absolute value of any standard numeric type (that uses the MSB as a sign bit, but not Q numbers) passed in as *n*. The function is signed/unsigned type safe.

**Q\_SHL**() and **Q\_SHR**() return the integral value *v* left or right shifted by the appropriate amount for *q*.

**Q\_MAXSTRLEN**() calculates the maximum number of characters that may be required to render the C-string representation of *q* with numeric base *base*.

**Q\_TOSTR**() renders the C-string representation of *q* with numeric base *base* and fractional precision *prec* into *s* which has an available capacity of *slen* characters. *base* must be in range \[2,16\]. Specifying *prec* as -1 renders the number's fractional component with maximum precision. If *slen* is greater than zero but insufficient to hold the complete C-string, the '\\0' C-string terminator will be written to *\*s*, thereby returning a zero length C-string.

**Q\_DEBUG**() returns a format string and associated data suitable for printf-like rendering of debugging information pertaining to *q*. If either *prefmt* and/or *postfmt* are specified, they are prepended and appended to the resulting format string respectively. The *incfmt* boolean specifies whether to include (*true*) or exclude (*false*) the raw format string itself in the debugging output.

**Q\_DFV2BFV**() converts decimal fractional value *dfv* to its binary-encoded representation with *nfbits* of binary precision. *dfv* must be passed as a preprocessor literal to preserve leading zeroes. The returned value can be used to set a Q number's fractional bits, for example using **Q\_SFVAL**().

All of those functions operate on the following data types: *s8q\_t*, *u8q\_t*, *s16q\_t*, *u16q\_t*, *s32q\_t*, *u32q\_t*, *s64q\_t*, and *u64q\_t*, which are referred to generically as *QTYPE*. The *ITYPE* refers to the [stdint(7)](/stdint/7.md) integer types. *NTYPE* is used to refer to any numeric type and is therefore a superset of *QTYPE* and *ITYPE*.

For more details, see [qmath(3)](/qmath/3.md).

## RETURN VALUES

**Q\_INI**() returns the initialised Q number which can be used to chain initialise additional Q numbers.

**Q\_TOSTR**() returns a pointer to the '\\0' C-string terminator appended to *s* after the rendered numeric data, or NULL on buffer overflow.

**Q\_DFV2BFV**() returns the binary-encoded representation of decimal fractional value *dfv* with *nfbits* of binary precision.

## SEE ALSO

[errno(2)](/errno/2.md), [qmath(3)](/qmath/3.md), [stdint(7)](/stdint/7.md)

## HISTORY

The [qmath(3)](/qmath/3.md) functions first appeared in FreeBSD 13.0.

## AUTHORS

The [qmath(3)](/qmath/3.md) functions and this manual page were written by Lawrence Stewart ⟨*lstewart@FreeBSD.org*⟩ and sponsored by Netflix, Inc.