The branch main has been updated by fuz: URL: https://cgit.FreeBSD.org/src/commit/?id=d790b16bbf0c3055ef00200d01659dfb3c0e5e5e
commit d790b16bbf0c3055ef00200d01659dfb3c0e5e5e Author: Robert Clausecker <[email protected]> AuthorDate: 2025-11-18 17:31:07 +0000 Commit: Robert Clausecker <[email protected]> CommitDate: 2025-11-30 19:21:52 +0000 libc/stdbit: add man pages for stdbit functions This adds man pages for each group of functions in <stdbit.h>. The man pages have cross references to one-another. Cross references from external man pages to these will be added in a later commit. Reviewed by: [email protected], kib Approved by: markj (mentor) MFC after: 1 month Differential Revision: https://reviews.freebsd.org/D53659 --- lib/libc/stdbit/Makefile.inc | 15 ++++ lib/libc/stdbit/stdc_bit_ceil.3 | 81 +++++++++++++++++++++ lib/libc/stdbit/stdc_bit_floor.3 | 83 ++++++++++++++++++++++ lib/libc/stdbit/stdc_bit_width.3 | 104 +++++++++++++++++++++++++++ lib/libc/stdbit/stdc_count_ones.3 | 85 ++++++++++++++++++++++ lib/libc/stdbit/stdc_count_zeros.3 | 84 ++++++++++++++++++++++ lib/libc/stdbit/stdc_first_leading_one.3 | 93 ++++++++++++++++++++++++ lib/libc/stdbit/stdc_first_leading_zero.3 | 92 ++++++++++++++++++++++++ lib/libc/stdbit/stdc_first_trailing_one.3 | 110 +++++++++++++++++++++++++++++ lib/libc/stdbit/stdc_first_trailing_zero.3 | 93 ++++++++++++++++++++++++ lib/libc/stdbit/stdc_has_single_bit.3 | 98 +++++++++++++++++++++++++ lib/libc/stdbit/stdc_leading_ones.3 | 86 ++++++++++++++++++++++ lib/libc/stdbit/stdc_leading_zeros.3 | 86 ++++++++++++++++++++++ lib/libc/stdbit/stdc_trailing_ones.3 | 86 ++++++++++++++++++++++ lib/libc/stdbit/stdc_trailing_zeros.3 | 87 +++++++++++++++++++++++ 15 files changed, 1283 insertions(+) diff --git a/lib/libc/stdbit/Makefile.inc b/lib/libc/stdbit/Makefile.inc index 2ea96d2b6dfe..fceccb12b589 100644 --- a/lib/libc/stdbit/Makefile.inc +++ b/lib/libc/stdbit/Makefile.inc @@ -17,3 +17,18 @@ SRCS+= stdc_bit_ceil.c \ 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 index 000000000000..470b255f471e --- /dev/null +++ b/lib/libc/stdbit/stdc_bit_ceil.3 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_bit_floor.3 b/lib/libc/stdbit/stdc_bit_floor.3 new file mode 100644 index 000000000000..3e90c34f070f --- /dev/null +++ b/lib/libc/stdbit/stdc_bit_floor.3 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_bit_width.3 b/lib/libc/stdbit/stdc_bit_width.3 new file mode 100644 index 000000000000..8d59886818d3 --- /dev/null +++ b/lib/libc/stdbit/stdc_bit_width.3 @@ -0,0 +1,104 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_count_ones.3 b/lib/libc/stdbit/stdc_count_ones.3 new file mode 100644 index 000000000000..6de92216c24b --- /dev/null +++ b/lib/libc/stdbit/stdc_count_ones.3 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_count_zeros.3 b/lib/libc/stdbit/stdc_count_zeros.3 new file mode 100644 index 000000000000..762ba62d3793 --- /dev/null +++ b/lib/libc/stdbit/stdc_count_zeros.3 @@ -0,0 +1,84 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_first_leading_one.3 b/lib/libc/stdbit/stdc_first_leading_one.3 new file mode 100644 index 000000000000..48f62d997043 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_leading_one.3 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_first_leading_zero.3 b/lib/libc/stdbit/stdc_first_leading_zero.3 new file mode 100644 index 000000000000..317b6263acb0 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_leading_zero.3 @@ -0,0 +1,92 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_first_trailing_one.3 b/lib/libc/stdbit/stdc_first_trailing_one.3 new file mode 100644 index 000000000000..0b590ac39732 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_trailing_one.3 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_first_trailing_zero.3 b/lib/libc/stdbit/stdc_first_trailing_zero.3 new file mode 100644 index 000000000000..bc4f7982d765 --- /dev/null +++ b/lib/libc/stdbit/stdc_first_trailing_zero.3 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 [email protected] diff --git a/lib/libc/stdbit/stdc_has_single_bit.3 b/lib/libc/stdbit/stdc_has_single_bit.3 new file mode 100644 index 000000000000..8f82c552216a --- /dev/null +++ b/lib/libc/stdbit/stdc_has_single_bit.3 @@ -0,0 +1,98 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <[email protected]> +.\" +.\" 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 *** 427 LINES SKIPPED ***
