.\" .\" This file and its contents are supplied under the terms of the .\" Common Development and Distribution License ("CDDL"), version 1.0. .\" You may only use this file in accordance with the terms of version .\" 1.0 of the CDDL. .\" .\" A full copy of the text of the CDDL should have accompanied this .\" source. A copy of the CDDL is also available via the Internet at .\" http://www.illumos.org/license/CDDL. .\" .\" .\" Copyright 2024 Oxide Computer Company .\" .Dd October 27, 2024 .Dt STDC_FIRST_TRAILING_ONE 3C .Os .Sh NAME .Nm stdc_first_trailing_one , .Nm stdc_first_trailing_one_uc , .Nm stdc_first_trailing_one_us , .Nm stdc_first_trailing_one_ui , .Nm stdc_first_trailing_one_ul , .Nm stdc_first_trailing_one_ull .Nd find index of least significant one bit .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdbit.h .Ft "unsigned int" .Fo stdc_first_trailing_one .Fa "generic_value_type value" .Fc .Ft "unsigned int" .Fo stdc_first_trailing_one_uc .Fa "unsigned char value" .Fc .Ft "unsigned int" .Fo stdc_first_trailing_one_us .Fa "unsigned short value" .Fc .Ft "unsigned int" .Fo stdc_first_trailing_one_ui .Fa "unsigned int value" .Fc .Ft "unsigned int" .Fo stdc_first_trailing_one_ul .Fa "unsigned long value" .Fc .Ft "unsigned int" .Fo stdc_first_trailing_one_ull .Fa "unsigned long long value" .Fc .Sh DESCRIPTION The .Fn stdc_first_trailing_one family of functions returns the 1s-based index of the first one bit in .Fa value starting at the least significant bit. If there is no one bit in .Fa value then zero is returned. .Pp These functions are sometimes called .Dq find first set and signed equivalents exist with .Xr ffs 3C . .Pp The .Fn stdc_first_trailing_one function is generic and will operate on all 8, 16, 32, and 64-bit unsigned integers; however, it is only available in C23. The other functions all operate on a specific integer type, but otherwise behave the same and are available regardless of the C language version. .Sh RETURN VALUES The functions in the .Fn stdc_first_trailing_one family always return the index of the first trailing one bit in .Fa value plus one. Otherwise, if there are no one bits in .Fa value , 0 will be returned. These functions cannot fail. .Sh EXAMPLES .Sy Example 1 Printing the index of the first trailing zero. .Bd -literal #include <stdbit.h> #include <stdio.h> #include <limits.h> int main(void) { printf("0x%x 0x%x 0x%x 0x%x\en", stdc_first_trailing_one_uc(0x2b), stdc_first_trailing_one_us(0x8000), stdc_first_trailing_one_ui(UINT32_MAX), stdc_first_trailing_one_ull(0xff60000000000000)); return (0); } .Ed .Pp When compiled and run, this produces: .Bd -literal -offset indent $ ./a.out 0x1 0x10 0x1 0x36 .Ed .Sh INTERFACE STABILITY .Sy Committed .Sh MT-LEVEL .Sy Async-Signal-Safe .Sh SEE ALSO .Xr ffs 3C , .Xr stdc_bit_ceil 3C , .Xr stdc_bit_floor 3C , .Xr stdc_bit_width 3C , .Xr stdc_count_ones 3C , .Xr stdc_count_zeros 3C , .Xr stdc_first_leading_one 3C , .Xr stdc_first_leading_zero 3C , .Xr stdc_first_trailing_zero 3C , .Xr stdc_has_single_bit 3C , .Xr stdc_leading_ones 3C , .Xr stdc_leading_zeros 3C , .Xr stdc_trailing_ones 3C , .Xr stdc_trailing_zeros 3C , .Xr stdbit.h 3HEAD