diff --git a/lib/libc/stdbit/Makefile.inc b/lib/libc/stdbit/Makefile.inc --- a/lib/libc/stdbit/Makefile.inc +++ b/lib/libc/stdbit/Makefile.inc @@ -17,3 +17,18 @@ stdc_trailing_zeros.c SYM_MAPS+=${LIBC_SRCTOP}/stdbit/Symbol.map + +MAN+= stdc_bit_ceil.3 + stdc_bit_floor.3 \ + stdc_bit_width.3 \ + stdc_count_ones.3 \ + stdc_count_zeros.3 \ + stdc_first_leading_one.3 \ + stdc_first_leading_zero.3 \ + stdc_first_trailing_one.3 \ + stdc_first_trailing_zero.3 \ + stdc_has_single_bit.3 \ + stdc_leading_ones.3 \ + stdc_leading_zeros.3 \ + stdc_trailing_ones.3 \ + stdc_trailing_zeros.3 diff --git a/lib/libc/stdbit/stdc_bit_ceil.3 b/lib/libc/stdbit/stdc_bit_ceil.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_bit_ceil.3 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_BIT_CEIL 3 +.Os +.Sh NAME +.Nm stdc_bit_ceil +.Nd round up to the next power of\~2 +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned char +.Fn stdc_bit_ceil_uc "unsigned char value" +.Ft unsigned short +.Fn stdc_bit_ceil_us "unsigned short value" +.Ft unsigned int +.Fn stdc_bit_ceil_ui "unsigned int value" +.Ft unsigned long +.Fn stdc_bit_ceil_ul "unsigned long value" +.Ft unsigned long long +.Fn stdc_bit_ceil_ull "unsigned long long value" +.Ft typeof Ns Pq Em value +.Fn stdc_bit_ceil "value" +.Sh DESCRIPTION +The +.Nm stdc_bit_ceil_ Ns Em type Ns () +family of functions rounds +.Fa value +up to the next power of\~2, where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_bit_ceil "value" +type-generic macro picks the appropriate +.Nm stdc_bit_ceil_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns +.Fa value +round up to the next power of\~2. +If this value is not representable, +0\~is returned. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_bit_floor 3 +.Sh STANDARDS +The +.Nm stdc_bit_ceil_ Ns Em type Ns () +family of functions and the +.Fn stdc_bit_ceil +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_bit_ceil_ Ns Em type Ns () +family of functions and the +.Fn stdc_bit_ceil +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_bit_floor.3 b/lib/libc/stdbit/stdc_bit_floor.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_bit_floor.3 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_BIT_FLOOR 3 +.Os +.Sh NAME +.Nm stdc_bit_floor +.Nd round down to the previous power of\~2 +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned char +.Fn stdc_bit_floor_uc "unsigned char value" +.Ft unsigned short +.Fn stdc_bit_floor_us "unsigned short value" +.Ft unsigned int +.Fn stdc_bit_floor_ui "unsigned int value" +.Ft unsigned long +.Fn stdc_bit_floor_ul "unsigned long value" +.Ft unsigned long long +.Fn stdc_bit_floor_ull "unsigned long long value" +.Ft typeof Ns Pq Em value +.Fn stdc_bit_floor "value" +.Sh DESCRIPTION +The +.Nm stdc_bit_floor_ Ns Em type Ns () +family of functions rounds +.Fa value +down to the previous power of\~2, where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_bit_floor "value" +type-generic macro picks the appropriate +.Nm stdc_bit_floor_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns +.Fa value +round down to the previous power of\~2. +If +.Fa value +is equal to zero, +zero is returned. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_bit_ceil 3 +.Sh STANDARDS +The +.Nm stdc_bit_floor_ Ns Em type Ns () +family of functions and the +.Fn stdc_bit_floor +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_bit_floor_ Ns Em type Ns () +family of functions and the +.Fn stdc_bit_floor +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_bit_width.3 b/lib/libc/stdbit/stdc_bit_width.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_bit_width.3 @@ -0,0 +1,104 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_BIT_WIDTH 3 +.Os +.Sh NAME +.Nm stdc_bit_width +.Nd find the first trailing one in an intege +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_bit_width_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_bit_width_us "unsigned short value" +.Ft unsigned int +.Fn stdc_bit_width_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_bit_width_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_bit_width_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_bit_width "value" +.Sh DESCRIPTION +The +.Nm stdc_bit_width_ Ns Em type Ns () +family of functions returns the number of bits needed to represent +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_bit_width "value" +type-generic macro picks the appropriate +.Nm stdc_bit_width_ Ns Em type Ns () +function based on the type of +.Fa value . +.Pp +Functions +.Fn stdc_bit_width_ui , +.Fn stdc_bit_width_ul , +and +.Fn stdc_bit_width_ull +are identical to +.Bx 4.3 +functions +.Xr fls 3 , +.Xr flsl 3 , +and +.Xr flsll 3 +respectively, except for operating on unsigned instead of signed values. +.Sh RETURN VALUES +Returns the least number of bits needed to represent +.Fa value . +If +.Fa value +is zero, the return value is zero. +Otherwise it is +.EQ +1 + \(lf log sub 2 italic value \(rf . +.EN +.Sh SEE ALSO +.Xr bit_fls 3 , +.Xr fls 3 , +.Xr flsl 3 , +.Xr flsll 3 , +.Xr stdbit 3 , +.Xr stdc_count_leading_zeros 3 , +.Xr stdc_first_leading_one 3 +.Sh STANDARDS +The +.Nm stdc_bit_width_ Ns Em type Ns () +family of functions and the +.Fn stdc_bit_width +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_bit_width_ Ns Em type Ns () +family of functions and the +.Fn stdc_bit_width +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_count_ones.3 b/lib/libc/stdbit/stdc_count_ones.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_count_ones.3 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_COUNT_ONES 3 +.Os +.Sh NAME +.Nm stdc_count_ones +.Nd count the ones in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_count_ones_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_count_ones_us "unsigned short value" +.Ft unsigned int +.Fn stdc_count_ones_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_count_ones_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_count_ones_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_count_ones "value" +.Sh DESCRIPTION +The +.Nm stdc_count_ones_ Ns Em type Ns () +family of functions returns the number of bits set to\~1 in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +This is also known as the +.Dq population count +(popcount) or +.Dq Hamming weight +operation. +The +.Fn stdc_count_ones "value" +type-generic macro picks the appropriate +.Nm stdc_count_ones_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the number of bits set to\~1 in +.Fa value . +.Sh SEE ALSO +.Xr bit_count 3 , +.Xr stdbit 3 , +.Xr stdc_count_zeros 3 , +.Xr stdc_has_single_bit 3 +.Sh STANDARDS +The +.Nm stdc_count_ones_ Ns Em type Ns () +family of functions and the +.Fn stdc_count_ones +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_count_ones_ Ns Em type Ns () +family of functions and the +.Fn stdc_count_ones +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_count_zeros.3 b/lib/libc/stdbit/stdc_count_zeros.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_count_zeros.3 @@ -0,0 +1,84 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_COUNT_ZEROS 3 +.Os +.Sh NAME +.Nm stdc_count_zeros +.Nd count the zeros in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_count_zeros_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_count_zeros_us "unsigned short value" +.Ft unsigned int +.Fn stdc_count_zeros_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_count_zeros_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_count_zeros_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_count_zeros "value" +.Sh DESCRIPTION +The +.Nm stdc_count_zeros_ Ns Em type Ns () +family of functions returns the number of bits set to\~0 in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +This is also known as the +.Dq population count +(popcount) or +.Dq Hamming weight +of the complement of +.Fa value . +The +.Fn stdc_count_zeros "value" +type-generic macro picks the appropriate +.Nm stdc_count_zeros_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the number of bits set to\~0 in +.Fa value . +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_count_ones 3 +.Sh STANDARDS +The +.Nm stdc_count_zeros_ Ns Em type Ns () +family of functions and the +.Fn stdc_count_zeros +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_count_zeros_ Ns Em type Ns () +family of functions and the +.Fn stdc_count_zeros +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_first_leading_one.3 b/lib/libc/stdbit/stdc_first_leading_one.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_leading_one.3 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_FIRST_LEADING_ONE 3 +.Os +.Sh NAME +.Nm stdc_first_leading_one +.Nd find the first leading one in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_first_leading_one_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_first_leading_one_us "unsigned short value" +.Ft unsigned int +.Fn stdc_first_leading_one_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_first_leading_one_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_first_leading_one_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_first_leading_one "value" +.Sh DESCRIPTION +The +.Nm stdc_first_leading_one_ Ns Em type Ns () +family of functions returns the index of the most significant set bit in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_first_leading_one "value" +type-generic macro picks the appropriate +.Nm stdc_first_leading_one_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the index of the most significant set bit in +.Fa value . +The bits are numbered such that the most significant bit has number\~1, +and the least significant bit has number +.Ms w +where +.Ms w +is the number of bits in the type of +.Fa value . +If no bits are set in +.Fa value +(i.\^e.\& +.Fa value +is zero), zero is returned. +.Sh SEE ALSO +.Xr fls 3 , +.Xr stdbit 3 , +.Xr stdc_leading_zeros 3 , +.Xr stdc_first_leading_zero 3 , +.Xr stdc_first_trailing_one 3 +.Sh STANDARDS +The +.Nm stdc_first_leading_one_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_leading_one +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_first_leading_one_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_leading_one +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_first_leading_zero.3 b/lib/libc/stdbit/stdc_first_leading_zero.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_leading_zero.3 @@ -0,0 +1,92 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_FIRST_LEADING_ZERO 3 +.Os +.Sh NAME +.Nm stdc_first_leading_zero +.Nd find the first leading zero in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_first_leading_zero_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_first_leading_zero_us "unsigned short value" +.Ft unsigned int +.Fn stdc_first_leading_zero_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_first_leading_zero_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_first_leading_zero_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_first_leading_zero "value" +.Sh DESCRIPTION +The +.Nm stdc_first_leading_zero_ Ns Em type Ns () +family of functions returns the index of the most significant clear bit in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_first_leading_zero "value" +type-generic macro picks the appropriate +.Nm stdc_first_leading_zero_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the index of the most significant clear bit in +.Fa value . +The bits are numbered such that the most significant bit has number\~1, +and the least significant bit has number +.Ms w +where +.Ms w +is the number of bits in the type of +.Fa value . +If no bits are clear in +.Fa value +(i.\^e.\& +.Fa value +is the bitwise complement of zero), zero is returned. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_leading_ones 3 , +.Xr stdc_first_leading_ones 3 , +.Xr stdc_first_trailing_zero 3 +.Sh STANDARDS +The +.Nm stdc_first_leading_zero_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_leading_zero +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_first_leading_zero_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_leading_zero +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_first_trailing_one.3 b/lib/libc/stdbit/stdc_first_trailing_one.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_trailing_one.3 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_FIRST_TRAILING_ONE 3 +.Os +.Sh NAME +.Nm stdc_first_trailing_one +.Nd find the first trailing one in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_first_trailing_one_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_first_trailing_one_us "unsigned short value" +.Ft unsigned int +.Fn stdc_first_trailing_one_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_first_trailing_one_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_first_trailing_one_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_first_trailing_one "value" +.Sh DESCRIPTION +The +.Nm stdc_first_trailing_one_ Ns Em type Ns () +family of functions returns the index of the least significant set bit in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_first_trailing_one "value" +type-generic macro picks the appropriate +.Nm stdc_first_trailing_one_ Ns Em type Ns () +function based on the type of +.Fa value . +.Pp +Functions +.Fn stdc_first_trailing_one_ui , +.Fn stdc_first_trailing_one_ul , +and +.Fn stdc_first_trailing_one_ull +are identical to +.Bx 4.3 +functions +.Xr ffs 3 , +.Xr ffsl 3 , +and +.Xr ffsll 3 +respectively, except for operating on unsigned instead of signed values. +.Sh RETURN VALUES +Returns the index of the least significant set bit in +.Fa value . +The bits are numbered such that the least significant bit has number\~1, +and the most significant bit has number +.Ms w +where +.Ms w +is the number of bits in the type of +.Fa value . +If no bits are set in +.Fa value +(i.\^e.\& +.Fa value +is zero), one is returned. +.Sh SEE ALSO +.Xr bit_ffs 3 , +.Xr ffs 3 , +.Xr ffsl 3 , +.Xr ffsll 3 , +.Xr stdbit 3 , +.Xr stdc_trailing_zeros 3 , +.Xr stdc_first_trailing_zero 3 , +.Xr stdc_first_leading_one 3 +.Sh STANDARDS +The +.Nm stdc_first_trailing_one_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_trailing_one +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_first_trailing_one_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_trailing_one +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_first_trailing_zero.3 b/lib/libc/stdbit/stdc_first_trailing_zero.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_trailing_zero.3 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_FIRST_TRAILING_ZERO 3 +.Os +.Sh NAME +.Nm stdc_first_trailing_zero +.Nd find the first trailing zero in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_first_trailing_zero_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_first_trailing_zero_us "unsigned short value" +.Ft unsigned int +.Fn stdc_first_trailing_zero_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_first_trailing_zero_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_first_trailing_zero_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_first_trailing_zero "value" +.Sh DESCRIPTION +The +.Nm stdc_first_trailing_zero_ Ns Em type Ns () +family of functions returns the index of the least significant clear bit in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_first_trailing_zero "value" +type-generic macro picks the appropriate +.Nm stdc_first_trailing_zero_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the index of the least significant clear bit in +.Fa value . +The bits are numbered such that the least significant bit has number\~1, +and the most significant bit has number +.Ms w +where +.Ms w +is the number of bits in the type of +.Fa value . +If no bits are clear in +.Fa value +(i.\^e.\& +.Fa value +is the bitwise complement of zero), zero is returned. +.Sh SEE ALSO +.Xr bit_ffc 3 , +.Xr stdbit 3 , +.Xr stdc_trailing_ones 3 , +.Xr stdc_first_trailing_ones 3 , +.Xr stdc_first_leading_zero 3 +.Sh STANDARDS +The +.Nm stdc_first_trailing_zero_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_trailing_zero +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_first_trailing_zero_ Ns Em type Ns () +family of functions and the +.Fn stdc_first_trailing_zero +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_has_single_bit.3 b/lib/libc/stdbit/stdc_has_single_bit.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_has_single_bit.3 @@ -0,0 +1,98 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_HAS_SINGLE_BIT 3 +.Os +.Sh NAME +.Nm stdc_has_single_bit +.Nd check for single bit set +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft bool +.Fn stdc_has_single_bit_uc "unsigned char value" +.Ft bool +.Fn stdc_has_single_bit_us "unsigned short value" +.Ft bool +.Fn stdc_has_single_bit_ui "unsigned int value" +.Ft bool +.Fn stdc_has_single_bit_ul "unsigned long value" +.Ft bool +.Fn stdc_has_single_bit_ull "unsigned long long value" +.Ft bool +.Fn stdc_has_single_bit "value" +.Sh DESCRIPTION +The +.Nm stdc_has_single_bit_ Ns Em type Ns () +family of functions checks if there is exactly one bit +set in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_has_single_bit "value" +type-generic macro picks the appropriate +.Nm stdc_has_single_bit_ Ns Em type Ns () +function based on the type of +.Fa value . +.Pp +The functions in this family behave similarly to the +.Fn powerof2 "value" +macro of +.In sys/param.h , +but differ when +.Fa value +is zero: while +.Fn powerof2 +considers zero to be a power of two, +.Fn stdc_has_single_bit +does not. +.Sh RETURN VALUES +Returns +.Sy true +if exactly one bit is set in +.Fa value , +otherwise returns +.Sy false . +I.\^e. the function determines if +.Fa value +is a power of two. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_count_ones 3 +.Sh STANDARDS +The +.Nm stdc_has_single_bit_ Ns Em type Ns () +family of functions and the +.Fn stdc_has_single_bit +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_has_single_bit_ Ns Em type Ns () +family of functions and the +.Fn stdc_has_single_bit +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_leading_ones.3 b/lib/libc/stdbit/stdc_leading_ones.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_leading_ones.3 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_LEADING_ONES 3 +.Os +.Sh NAME +.Nm stdc_leading_ones +.Nd find the number of leading ones in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_leading_ones_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_leading_ones_us "unsigned short value" +.Ft unsigned int +.Fn stdc_leading_ones_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_leading_ones_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_leading_ones_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_leading_ones "value" +.Sh DESCRIPTION +The +.Nm stdc_leading_ones_ Ns Em type Ns () +family of functions returns the number of leading ones in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_leading_ones "value" +type-generic macro picks the appropriate +.Nm stdc_leading_ones_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the number of leading ones in +.Fa value . +If +.Fa value +is all ones, +the total number of bits in the type of +.Fa value +is returned. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_leading_zeros 3 , +.Xr stdc_trailing_ones 3 , +.Xr stdc_first_leading_zero 3 +.Sh STANDARDS +The +.Nm stdc_leading_ones_ Ns Em type Ns () +family of functions and the +.Fn stdc_leading_ones +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_leading_ones_ Ns Em type Ns () +family of functions and the +.Fn stdc_leading_ones +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_leading_zeros.3 b/lib/libc/stdbit/stdc_leading_zeros.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_leading_zeros.3 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_LEADING_ZEROS 3 +.Os +.Sh NAME +.Nm stdc_leading_zeros +.Nd find the number of leading zeros in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_leading_zeros_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_leading_zeros_us "unsigned short value" +.Ft unsigned int +.Fn stdc_leading_zeros_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_leading_zeros_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_leading_zeros_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_leading_zeros "value" +.Sh DESCRIPTION +The +.Nm stdc_leading_zeros_ Ns Em type Ns () +family of functions returns the number of leading zeros in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_leading_zeros "value" +type-generic macro picks the appropriate +.Nm stdc_leading_zeros_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the number of leading zeros in +.Fa value . +If +.Fa value +is all zeros, +the total number of bits in the type of +.Fa value +is returned. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_leading_ones 3 , +.Xr stdc_trailing_zeros 3 , +.Xr stdc_first_leading_one 3 +.Sh STANDARDS +The +.Nm stdc_leading_zeros_ Ns Em type Ns () +family of functions and the +.Fn stdc_leading_zeros +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_leading_zeros_ Ns Em type Ns () +family of functions and the +.Fn stdc_leading_zeros +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_trailing_ones.3 b/lib/libc/stdbit/stdc_trailing_ones.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_trailing_ones.3 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_TRAILING_ONES 3 +.Os +.Sh NAME +.Nm stdc_trailing_ones +.Nd find the number of trailing ones in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_trailing_ones_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_trailing_ones_us "unsigned short value" +.Ft unsigned int +.Fn stdc_trailing_ones_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_trailing_ones_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_trailing_ones_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_trailing_ones "value" +.Sh DESCRIPTION +The +.Nm stdc_trailing_ones_ Ns Em type Ns () +family of functions returns the number of trailing ones in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_trailing_ones "value" +type-generic macro picks the appropriate +.Nm stdc_trailing_ones_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the number of trailing ones in +.Fa value . +If +.Fa value +is all ones, +the total number of bits in the type of +.Fa value +is returned. +.Sh SEE ALSO +.Xr stdbit 3 , +.Xr stdc_leading_ones 3 , +.Xr stdc_trailing_zeros 3 , +.Xr stdc_first_trailing_zero 3 +.Sh STANDARDS +The +.Nm stdc_trailing_ones_ Ns Em type Ns () +family of functions and the +.Fn stdc_trailing_ones +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_trailing_ones_ Ns Em type Ns () +family of functions and the +.Fn stdc_trailing_ones +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/lib/libc/stdbit/stdc_trailing_zeros.3 b/lib/libc/stdbit/stdc_trailing_zeros.3 new file mode 100644 --- /dev/null +++ b/lib/libc/stdbit/stdc_trailing_zeros.3 @@ -0,0 +1,87 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDC_TRAILING_ZEROS 3 +.Os +.Sh NAME +.Nm stdc_trailing_zeros +.Nd find the number of trailing zeros in an integer +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Ft unsigned int +.Fn stdc_trailing_zeros_uc "unsigned char value" +.Ft unsigned int +.Fn stdc_trailing_zeros_us "unsigned short value" +.Ft unsigned int +.Fn stdc_trailing_zeros_ui "unsigned int value" +.Ft unsigned int +.Fn stdc_trailing_zeros_ul "unsigned long value" +.Ft unsigned int +.Fn stdc_trailing_zeros_ull "unsigned long long value" +.Ft unsigned int +.Fn stdc_trailing_zeros "value" +.Sh DESCRIPTION +The +.Nm stdc_trailing_zeros_ Ns Em type Ns () +family of functions returns the number of trailing zeros in +.Fa value , +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +The +.Fn stdc_trailing_zeros "value" +type-generic macro picks the appropriate +.Nm stdc_trailing_zeros_ Ns Em type Ns () +function based on the type of +.Fa value . +.Sh RETURN VALUES +Returns the number of trailing zeros in +.Fa value . +If +.Fa value +is all zeros, +the total number of bits in the type of +.Fa value +is returned. +.Sh SEE ALSO +.Xr ffs 3 , +.Xr stdbit 3 , +.Xr stdc_leading_zeros 3 , +.Xr stdc_trailing_ones 3 , +.Xr stdc_first_trailing_one 3 +.Sh STANDARDS +The +.Nm stdc_trailing_zeros_ Ns Em type Ns () +family of functions and the +.Fn stdc_trailing_zeros +type-generic macro conform to +.St -isoC-2023 . +.Sh HISTORY +The +.Nm stdc_trailing_zeros_ Ns Em type Ns () +family of functions and the +.Fn stdc_trailing_zeros +type-generic macro were added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org