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