1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" 14.Dd October 27, 2024 15.Dt STDC_FIRST_LEADING_ONE 9F 16.Os 17.Sh NAME 18.Nm stdc_first_leading_one , 19.Nm stdc_first_leading_one_uc , 20.Nm stdc_first_leading_one_us , 21.Nm stdc_first_leading_one_ui , 22.Nm stdc_first_leading_one_ul , 23.Nm stdc_first_leading_one_ull 24.Nd find index of most significant one bit 25.Sh SYNOPSIS 26.In sys/stdbit.h 27.Ft "unsigned int" 28.Fo stdc_first_leading_one 29.Fa "generic_value_type value" 30.Fc 31.Ft "unsigned int" 32.Fo stdc_first_leading_one_uc 33.Fa "unsigned char value" 34.Fc 35.Ft "unsigned int" 36.Fo stdc_first_leading_one_us 37.Fa "unsigned short value" 38.Fc 39.Ft "unsigned int" 40.Fo stdc_first_leading_one_ui 41.Fa "unsigned int value" 42.Fc 43.Ft "unsigned int" 44.Fo stdc_first_leading_one_ul 45.Fa "unsigned long value" 46.Fc 47.Ft "unsigned int" 48.Fo stdc_first_leading_one_ull 49.Fa "unsigned long long value" 50.Fc 51.Sh DESCRIPTION 52The 53.Fn stdc_first_leading_one 54family of functions returns the 1s-based index of the first one bit in 55.Fa value 56starting at the most significant bit. 57If there is no one bit in 58.Fa value 59then zero is returned. 60.Pp 61The 62.Fn stdc_first_leading_one 63function is generic and will operate on all 8, 16, 32, and 64-bit 64unsigned integers; however, it is only available in C23. 65The other functions all operate on a specific integer type, but 66otherwise behave the same and are available regardless of the C language 67version. 68.Pp 69The way that the index is constructed is not necessarily intuitive. 70The C standard counts the most significant index starting with the most 71significant bit as index value 0. 72Consider the 16-bit value 0x952b. 73Generally we would consider the value 74.Sq b 75as bits 0 to 3 while the value 76.Sq 9 77as bits 12 to 15. 78Bit 15 is actually most significant index 0. 79Bit 14, most significant index 1. 80Bit 0, most significant index 15. 81This example, 0x952b, would return the value 1 82.Po 83when using the generic or 84.Vt unsigned short 85form 86.Pc 87as the function is defined to return this particular index 88.Em plus one . 89Zero is reserved for when there is no leading zero bit at all. 90.Pp 91Note that if a non-zero unsigned integer is promoted, it will always be filled 92with leading zeros which will cause the returned value to increase as 93the first one bit is further away from the most significant bit. 94.Pp 95While this is similar in function to the 96.Xr ddi_fls 9F 97functions which find the last set value and identify the same bits, the 98.Xr ddi_fls 9F 99functions determine the index starting from the least significant bit, 100instead of the most significant bit. 101.Sh CONTEXT 102These functions may be called from 103.Sy user , 104.Sy kernel , 105or 106.Sy interrupt 107context. 108.Sh RETURN VALUES 109The functions in the 110.Fn stdc_first_leading_one 111family always return the most significant index of the first leading 112one bit in 113.Fa value , 114.Em plus one . 115Otherwise, if there are no one bits in 116.Fa value , 1170 will be returned. 118These functions cannot fail. 119.Sh INTERFACE STABILITY 120.Sy Committed 121.Sh SEE ALSO 122.Xr stdc_first_leading_one 3C , 123.Xr ddi_fls 9F , 124.Xr stdc_bit_ceil 9F , 125.Xr stdc_bit_floor 9F , 126.Xr stdc_bit_width 9F , 127.Xr stdc_count_ones 9F , 128.Xr stdc_count_zeros 9F , 129.Xr stdc_first_leading_zero 9F , 130.Xr stdc_first_trailing_one 9F , 131.Xr stdc_first_trailing_zero 9F , 132.Xr stdc_has_single_bit 9F , 133.Xr stdc_leading_ones 9F , 134.Xr stdc_leading_zeros 9F , 135.Xr stdc_trailing_ones 9F , 136.Xr stdc_trailing_zeros 9F 137