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 17, 2024 15.Dt STDBIT.H 3HEAD 16.Os 17.Sh NAME 18.Nm stdbit.h 19.Nd bit and byte utilities 20.Sh SYNOPSIS 21.In stdbit.h 22.Sh DESCRIPTION 23The 24.In stdbit.h 25header provides support for C23 bit and byte utilities. 26.Pp 27The 28.In stdbit.h 29header provides the ability to determine the endian mode of the system 30through a series of preprocessor macros at compilation time. 31For more information and examples of how the endian ordering impacts 32data layout, see 33.Xr endian 7 . 34.Bl -tag -width Ds 35.It Dv __STDC_ENDIAN_LITTLE__ 36This macro is an integer that represents a little-endian byte order. 37.It Dv __STDC_ENDIAN_BIG__ 38This macro is an integer that represents a big-endian byte order. 39.It Dv __STDC_ENDIAN_NATIVE__ 40This macro will be defined to indicate the byte order of the system and 41generally be defined to either 42.Dv __STDC_ENDIAN_LITTLE__ 43or 44.Dv __STDC_ENDIAN_BIG__ . 45While uncommon and not supported by illumos, if the system is neither 46little- or big-endian, then 47.Dv __STDC_ENDIAN_NATIVE__ 48will be defined to a different, platform-defined value. 49.El 50.Pp 51This functionality is analogous to that found in 52.Xr endian.h 3HEAD , 53but unlike 54.Xr endian.h 3HEAD , 55this header is standardized and a part of C23. 56.Pp 57The 58.In stdbit.h 59header makes available a number of different families of functions which 60operate on both fixed size integers and have generic forms. 61The generic forms require support for at least C23 to be requested, 62while the non-generic forms are always made available. 63These families are: 64.Bl -tag -width Ds 65.It Xr stdc_bit_ceil 3C 66Finds the smallest power of two that is equal to or larger than a given 67value. 68.It Xr stdc_bit_floor 3C 69Finds the largest power of two that is equal to or less than a given 70value. 71.It Xr stdc_bit_width 3C 72Determines the minimum number of bits required to store a given value. 73.It Xr stdc_count_ones 3C 74Counts the number of one bits in a value. 75This is sometimes called a population count. 76.It Xr stdc_count_zeros 3C 77Counts the number of zero bits in a value. 78.It Xr stdc_first_leading_one 3C 79Finds the first one bit starting from the most significant bit. 80.It Xr stdc_first_leading_zero 3C 81Finds the first zero bit starting from the most significant bit. 82.It Xr stdc_first_trailing_one 3C 83Finds the first one bit starting from the least significant bit. 84This is sometimes called find first set. 85.It Xr stdc_first_trailing_zero 3C 86Finds the first one zero starting from the least significant bit. 87.It Xr stdc_has_single_bit 3C 88Determines whether or not a value only has a single bit set. 89.It Xr stdc_leading_ones 3C 90Counts the number of consecutive one bits starting from the most 91significant bit. 92.It Xr stdc_leading_zeros 3C 93Counts the number of consecutive zero bits starting from the most 94significant bit. 95.It Xr stdc_trailing_ones 3C 96Counts the number of consecutive one bits starting from the least 97significant bit. 98.It Xr stdc_trailing_zeros 3C 99Counts the number of consecutive zero bits starting from the least 100significant bit. 101.El 102.Pp 103This same functionality is made available to device drivers through 104.In sys/stdbit.h . 105.Sh INTERFACE STABILITY 106.Sy Committed 107.Sh SEE ALSO 108.Xr stdc_bit_ceil 3C , 109.Xr stdc_bit_floor 3C , 110.Xr stdc_bit_width 3C , 111.Xr stdc_count_ones 3C , 112.Xr stdc_count_zeros 3C , 113.Xr stdc_first_leading_one 3C , 114.Xr stdc_first_leading_zero 3C , 115.Xr stdc_first_trailing_one 3C , 116.Xr stdc_first_trailing_zero 3C , 117.Xr stdc_has_single_bit 3C , 118.Xr stdc_leading_ones 3C , 119.Xr stdc_leading_zeros 3C , 120.Xr stdc_trailing_ones 3C , 121.Xr stdc_trailing_zeros 3C , 122.Xr endian.h 3HEAD , 123.Xr endian 7 124