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_TRAILING_ONE 3C 16.Os 17.Sh NAME 18.Nm stdc_first_trailing_one , 19.Nm stdc_first_trailing_one_uc , 20.Nm stdc_first_trailing_one_us , 21.Nm stdc_first_trailing_one_ui , 22.Nm stdc_first_trailing_one_ul , 23.Nm stdc_first_trailing_one_ull 24.Nd find index of least significant one bit 25.Sh LIBRARY 26.Lb libc 27.Sh SYNOPSIS 28.In stdbit.h 29.Ft "unsigned int" 30.Fo stdc_first_trailing_one 31.Fa "generic_value_type value" 32.Fc 33.Ft "unsigned int" 34.Fo stdc_first_trailing_one_uc 35.Fa "unsigned char value" 36.Fc 37.Ft "unsigned int" 38.Fo stdc_first_trailing_one_us 39.Fa "unsigned short value" 40.Fc 41.Ft "unsigned int" 42.Fo stdc_first_trailing_one_ui 43.Fa "unsigned int value" 44.Fc 45.Ft "unsigned int" 46.Fo stdc_first_trailing_one_ul 47.Fa "unsigned long value" 48.Fc 49.Ft "unsigned int" 50.Fo stdc_first_trailing_one_ull 51.Fa "unsigned long long value" 52.Fc 53.Sh DESCRIPTION 54The 55.Fn stdc_first_trailing_one 56family of functions returns the 1s-based index of the first one bit in 57.Fa value 58starting at the least significant bit. 59If there is no one bit in 60.Fa value 61then zero is returned. 62.Pp 63These functions are sometimes called 64.Dq find first set 65and signed equivalents exist with 66.Xr ffs 3C . 67.Pp 68The 69.Fn stdc_first_trailing_one 70function is generic and will operate on all 8, 16, 32, and 64-bit 71unsigned integers; however, it is only available in C23. 72The other functions all operate on a specific integer type, but 73otherwise behave the same and are available regardless of the C language 74version. 75.Sh RETURN VALUES 76The functions in the 77.Fn stdc_first_trailing_one 78family always return the index of the first trailing 79one bit in 80.Fa value 81plus one. 82Otherwise, if there are no one bits in 83.Fa value , 840 will be returned. 85These functions cannot fail. 86.Sh EXAMPLES 87.Sy Example 1 88Printing the index of the first trailing zero. 89.Bd -literal 90#include <stdbit.h> 91#include <stdio.h> 92#include <limits.h> 93 94int 95main(void) 96{ 97 printf("0x%x 0x%x 0x%x 0x%x\en", 98 stdc_first_trailing_one_uc(0x2b), 99 stdc_first_trailing_one_us(0x8000), 100 stdc_first_trailing_one_ui(UINT32_MAX), 101 stdc_first_trailing_one_ull(0xff60000000000000)); 102 return (0); 103} 104.Ed 105.Pp 106When compiled and run, this produces: 107.Bd -literal -offset indent 108$ ./a.out 1090x1 0x10 0x1 0x36 110.Ed 111.Sh INTERFACE STABILITY 112.Sy Committed 113.Sh MT-LEVEL 114.Sy Async-Signal-Safe 115.Sh SEE ALSO 116.Xr ffs 3C , 117.Xr stdc_bit_ceil 3C , 118.Xr stdc_bit_floor 3C , 119.Xr stdc_bit_width 3C , 120.Xr stdc_count_ones 3C , 121.Xr stdc_count_zeros 3C , 122.Xr stdc_first_leading_one 3C , 123.Xr stdc_first_leading_zero 3C , 124.Xr stdc_first_trailing_zero 3C , 125.Xr stdc_has_single_bit 3C , 126.Xr stdc_leading_ones 3C , 127.Xr stdc_leading_zeros 3C , 128.Xr stdc_trailing_ones 3C , 129.Xr stdc_trailing_zeros 3C , 130.Xr stdbit.h 3HEAD 131