illumos: manual page: stdc_first_leading

STDC_FIRST_LEADING_ZERO(9F) Kernel Functions for Drivers

NAME

stdc_first_leading_zero, stdc_first_leading_zero_uc,
stdc_first_leading_zero_us, stdc_first_leading_zero_ui,
stdc_first_leading_zero_ul, stdc_first_leading_zero_ull - find index of
most significant zero bit

SYNOPSIS

#include <sys/stdbit.h>

unsigned int
stdc_first_leading_zero(generic_value_type value);

unsigned int
stdc_first_leading_zero_uc(unsigned char value);

unsigned int
stdc_first_leading_zero_us(unsigned short value);

unsigned int
stdc_first_leading_zero_ui(unsigned int value);

unsigned int
stdc_first_leading_zero_ul(unsigned long value);

unsigned int
stdc_first_leading_zero_ull(unsigned long long value);

DESCRIPTION

The stdc_first_leading_zero() family of functions returns the 1s-based
index of the first zero bit in value starting at the most significant bit.
If there is no zero bit in value then zero is returned.

The stdc_first_leading_zero() function is generic and will operate on all
8, 16, 32, and 64-bit unsigned integers; however, it is only available in
C23. The other functions all operate on a specific integer type, but
otherwise behave the same and are available regardless of the C language
version.

The way that the index is constructed is not necessarily intuitive. The C
standard counts the most significant index starting with the most
significant bit as index value 0. Consider the 16-bit value 0x952b.
Generally we would consider the value `b' as bits 0 to 3 while the value
`9' as bits 12 to 15. Bit 15 is actually most significant index 0. Bit
14, most significant index 1. Bit 0, most significant index 15. This
example, 0x952b, would return the value 2 (when using the generic or
unsigned short form) as the function is defined to return this particular
index plus one. Zero is reserved for when there is no leading zero bit at
all.

Note that if an unsigned integer is promoted, it will always be filled with
leading zeros which will cause the function to return 1.

CONTEXT

These functions may be called from user, kernel, or interrupt context.

RETURN VALUES

The functions in the stdc_first_leading_zero() family always return the
most significant index of the first leading zero bit in value, plus one.
Otherwise, if there are no zero bits in value, 0 will be returned. These
functions cannot fail.

INTERFACE STABILITY