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