1*aaceae98SRobert Mustacchi.\" 2*aaceae98SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*aaceae98SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*aaceae98SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*aaceae98SRobert Mustacchi.\" 1.0 of the CDDL. 6*aaceae98SRobert Mustacchi.\" 7*aaceae98SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*aaceae98SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*aaceae98SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*aaceae98SRobert Mustacchi.\" 11*aaceae98SRobert Mustacchi.\" 12*aaceae98SRobert Mustacchi.\" Copyright 2024 Oxide Computer Company 13*aaceae98SRobert Mustacchi.\" 14*aaceae98SRobert Mustacchi.Dd October 27, 2024 15*aaceae98SRobert Mustacchi.Dt STDC_FIRST_LEADING_ZERO 3C 16*aaceae98SRobert Mustacchi.Os 17*aaceae98SRobert Mustacchi.Sh NAME 18*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero , 19*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_uc , 20*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_us , 21*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_ui , 22*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_ul , 23*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_ull 24*aaceae98SRobert Mustacchi.Nd find index of most significant zero bit 25*aaceae98SRobert Mustacchi.Sh LIBRARY 26*aaceae98SRobert Mustacchi.Lb libc 27*aaceae98SRobert Mustacchi.Sh SYNOPSIS 28*aaceae98SRobert Mustacchi.In stdbit.h 29*aaceae98SRobert Mustacchi.Ft "unsigned int" 30*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero 31*aaceae98SRobert Mustacchi.Fa "generic_value_type value" 32*aaceae98SRobert Mustacchi.Fc 33*aaceae98SRobert Mustacchi.Ft "unsigned int" 34*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_uc 35*aaceae98SRobert Mustacchi.Fa "unsigned char value" 36*aaceae98SRobert Mustacchi.Fc 37*aaceae98SRobert Mustacchi.Ft "unsigned int" 38*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_us 39*aaceae98SRobert Mustacchi.Fa "unsigned short value" 40*aaceae98SRobert Mustacchi.Fc 41*aaceae98SRobert Mustacchi.Ft "unsigned int" 42*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_ui 43*aaceae98SRobert Mustacchi.Fa "unsigned int value" 44*aaceae98SRobert Mustacchi.Fc 45*aaceae98SRobert Mustacchi.Ft "unsigned int" 46*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_ul 47*aaceae98SRobert Mustacchi.Fa "unsigned long value" 48*aaceae98SRobert Mustacchi.Fc 49*aaceae98SRobert Mustacchi.Ft "unsigned int" 50*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_ull 51*aaceae98SRobert Mustacchi.Fa "unsigned long long value" 52*aaceae98SRobert Mustacchi.Fc 53*aaceae98SRobert Mustacchi.Sh DESCRIPTION 54*aaceae98SRobert MustacchiThe 55*aaceae98SRobert Mustacchi.Fn stdc_first_leading_zero 56*aaceae98SRobert Mustacchifamily of functions returns the 1s-based index of the first zero bit in 57*aaceae98SRobert Mustacchi.Fa value 58*aaceae98SRobert Mustacchistarting at the most significant bit. 59*aaceae98SRobert MustacchiIf there is no zero bit in 60*aaceae98SRobert Mustacchi.Fa value 61*aaceae98SRobert Mustacchithen zero is returned. 62*aaceae98SRobert Mustacchi.Pp 63*aaceae98SRobert MustacchiThe 64*aaceae98SRobert Mustacchi.Fn stdc_first_leading_zero 65*aaceae98SRobert Mustacchifunction is generic and will operate on all 8, 16, 32, and 64-bit 66*aaceae98SRobert Mustacchiunsigned integers; however, it is only available in C23. 67*aaceae98SRobert MustacchiThe other functions all operate on a specific integer type, but 68*aaceae98SRobert Mustacchiotherwise behave the same and are available regardless of the C language 69*aaceae98SRobert Mustacchiversion. 70*aaceae98SRobert Mustacchi.Pp 71*aaceae98SRobert MustacchiThe way that the index is constructed is not necessarily intuitive. 72*aaceae98SRobert MustacchiThe C standard counts the most significant index starting with the most 73*aaceae98SRobert Mustacchisignificant bit as index value 0. 74*aaceae98SRobert MustacchiConsider the 16-bit value 0x952b. 75*aaceae98SRobert MustacchiGenerally we would consider the value 76*aaceae98SRobert Mustacchi.Sq b 77*aaceae98SRobert Mustacchias bits 0 to 3 while the value 78*aaceae98SRobert Mustacchi.Sq 9 79*aaceae98SRobert Mustacchias bits 12 to 15. 80*aaceae98SRobert MustacchiBit 15 is actually most significant index 0. 81*aaceae98SRobert MustacchiBit 14, most significant index 1. 82*aaceae98SRobert MustacchiBit 0, most significant index 15. 83*aaceae98SRobert MustacchiThis example, 0x952b, would return the value 2 84*aaceae98SRobert Mustacchi.Po 85*aaceae98SRobert Mustacchiwhen using the generic or 86*aaceae98SRobert Mustacchi.Vt unsigned short 87*aaceae98SRobert Mustacchiform 88*aaceae98SRobert Mustacchi.Pc 89*aaceae98SRobert Mustacchias the function is defined to return this particular index 90*aaceae98SRobert Mustacchi.Em plus one . 91*aaceae98SRobert MustacchiZero is reserved for when there is no leading zero bit at all. 92*aaceae98SRobert Mustacchi.Pp 93*aaceae98SRobert MustacchiNote that if an unsigned integer is promoted, it will always be filled 94*aaceae98SRobert Mustacchiwith leading zeros which will cause the function to return 1. 95*aaceae98SRobert Mustacchi.Sh RETURN VALUES 96*aaceae98SRobert MustacchiThe functions in the 97*aaceae98SRobert Mustacchi.Fn stdc_first_leading_zero 98*aaceae98SRobert Mustacchifamily always return the most significant index of the first leading 99*aaceae98SRobert Mustacchizero bit in 100*aaceae98SRobert Mustacchi.Fa value , 101*aaceae98SRobert Mustacchi.Em plus one . 102*aaceae98SRobert MustacchiOtherwise, if there are no zero bits in 103*aaceae98SRobert Mustacchi.Fa value , 104*aaceae98SRobert Mustacchi0 will be returned. 105*aaceae98SRobert MustacchiThese functions cannot fail. 106*aaceae98SRobert Mustacchi.Sh EXAMPLES 107*aaceae98SRobert Mustacchi.Sy Example 1 108*aaceae98SRobert MustacchiPrinting the index of the first leading zero 109*aaceae98SRobert Mustacchi.Pq plus one . 110*aaceae98SRobert Mustacchi.Bd -literal 111*aaceae98SRobert Mustacchi#include <stdbit.h> 112*aaceae98SRobert Mustacchi#include <stdio.h> 113*aaceae98SRobert Mustacchi#include <limits.h> 114*aaceae98SRobert Mustacchi 115*aaceae98SRobert Mustacchiint 116*aaceae98SRobert Mustacchimain(void) 117*aaceae98SRobert Mustacchi{ 118*aaceae98SRobert Mustacchi printf("0x%x 0x%x 0x%x 0x%x\en", 119*aaceae98SRobert Mustacchi stdc_first_leading_zero_uc(0xf0), 120*aaceae98SRobert Mustacchi stdc_first_leading_zero_us(0xfabc), 121*aaceae98SRobert Mustacchi stdc_first_leading_zero_ui(UINT32_MAX), 122*aaceae98SRobert Mustacchi stdc_first_leading_zero_ull(0)); 123*aaceae98SRobert Mustacchi return (0); 124*aaceae98SRobert Mustacchi} 125*aaceae98SRobert Mustacchi.Ed 126*aaceae98SRobert Mustacchi.Pp 127*aaceae98SRobert MustacchiWhen compiled and run, this produces: 128*aaceae98SRobert Mustacchi.Bd -literal -offset indent 129*aaceae98SRobert Mustacchi$ ./a.out 130*aaceae98SRobert Mustacchi0x5 0x6 0x0 0x1 131*aaceae98SRobert Mustacchi.Ed 132*aaceae98SRobert Mustacchi.Sh INTERFACE STABILITY 133*aaceae98SRobert Mustacchi.Sy Committed 134*aaceae98SRobert Mustacchi.Sh MT-LEVEL 135*aaceae98SRobert Mustacchi.Sy Async-Signal-Safe 136*aaceae98SRobert Mustacchi.Sh SEE ALSO 137*aaceae98SRobert Mustacchi.Xr stdc_bit_ceil 3C , 138*aaceae98SRobert Mustacchi.Xr stdc_bit_floor 3C , 139*aaceae98SRobert Mustacchi.Xr stdc_bit_width 3C , 140*aaceae98SRobert Mustacchi.Xr stdc_count_ones 3C , 141*aaceae98SRobert Mustacchi.Xr stdc_count_zeros 3C , 142*aaceae98SRobert Mustacchi.Xr stdc_first_leading_one 3C , 143*aaceae98SRobert Mustacchi.Xr stdc_first_trailing_one 3C , 144*aaceae98SRobert Mustacchi.Xr stdc_first_trailing_zero 3C , 145*aaceae98SRobert Mustacchi.Xr stdc_has_single_bit 3C , 146*aaceae98SRobert Mustacchi.Xr stdc_leading_ones 3C , 147*aaceae98SRobert Mustacchi.Xr stdc_leading_zeros 3C , 148*aaceae98SRobert Mustacchi.Xr stdc_trailing_ones 3C , 149*aaceae98SRobert Mustacchi.Xr stdc_trailing_zeros 3C , 150*aaceae98SRobert Mustacchi.Xr stdbit.h 3HEAD 151