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_BIT_CEIL 3C 16.Os 17.Sh NAME 18.Nm stdc_bit_ceil , 19.Nm stdc_bit_ceil_uc , 20.Nm stdc_bit_ceil_us , 21.Nm stdc_bit_ceil_ui , 22.Nm stdc_bit_ceil_ul , 23.Nm stdc_bit_ceil_ull 24.Nd find smallest power of 2 not less than value 25.Sh LIBRARY 26.Lb libc 27.Sh SYNOPSIS 28.In stdbit.h 29.Ft generic_value_type 30.Fo stdc_bit_ceil 31.Fa "generic_value_type value" 32.Fc 33.Ft "unsigned char" 34.Fo stdc_bit_ceil_uc 35.Fa "unsigned char value" 36.Fc 37.Ft "unsigned short" 38.Fo stdc_bit_ceil_us 39.Fa "unsigned short value" 40.Fc 41.Ft "unsigned int" 42.Fo stdc_bit_ceil_ui 43.Fa "unsigned int value" 44.Fc 45.Ft "unsigned long" 46.Fo stdc_bit_ceil_ul 47.Fa "unsigned long value" 48.Fc 49.Ft "unsigned long long" 50.Fo stdc_bit_ceil_ull 51.Fa "unsigned long long value" 52.Fc 53.Sh DESCRIPTION 54The 55.Fn stdc_bit_ceil 56family of functions finds the smallest power of 2 that is not less than 57.Fa value . 58If the resulting value would not fit in the type, then 0 is returned. 59For example, if one were to use 60.Dv UINT8_MAX 61with 62.Fn stdc_bit_ceil_uc 63the next power of two would be 0x100, which is larger than would fit in 64an 8-bit unsigned char, resulting in 0. 65.Pp 66The 67.Fn stdc_bit_ceil 68function is generic and will operate on all 8, 16, 32, and 64-bit 69unsigned integers; however, it is only available in C23. 70The other functions all operate on a specific integer type, but 71otherwise behave the same and are available regardless of the C language 72version. 73.Sh RETURN VALUES 74The functions in the 75.Fn stdc_bit_ceil 76family returns the smallest power of 2 that is not less than 77.Fa value . 78These functions cannot fail. 79.Sh EXAMPLES 80.Sy Example 1 81Printing the bit ceiling of an integer. 82.Bd -literal 83#include <stdbit.h> 84#include <stdio.h> 85#include <limits.h> 86 87int 88main(void) 89{ 90 printf("0x%x 0x%x 0x%x 0x%llx\en", 91 stdc_bit_ceil_uc(0xd2), 92 stdc_bit_ceil_us(0x7777), 93 stdc_bit_ceil_ui(0x038fa0ff), 94 stdc_bit_ceil_ull(0)); 95 return (0); 96} 97.Ed 98.Pp 99When compiled and run, this produces: 100.Bd -literal -offset indent 101$ ./a.out 1020x0 0x8000 0x4000000 0x1 103.Ed 104.Sh INTERFACE STABILITY 105.Sy Committed 106.Sh MT-LEVEL 107.Sy Async-Signal-Safe 108.Sh SEE ALSO 109.Xr stdc_bit_floor 3C , 110.Xr stdc_bit_width 3C , 111.Xr stdc_count_ones 3C , 112.Xr stdc_count_zero 3C , 113.Xr stdc_first_leading_one 3C , 114.Xr stdc_first_leading_zero 3C , 115.Xr stdc_first_trailing_one 3C , 116.Xr stdc_first_trailing_zero 3C , 117.Xr stdc_has_single_bit 3C , 118.Xr stdc_leading_ones 3C , 119.Xr stdc_leading_zeros 3C , 120.Xr stdc_trailing_ones 3C , 121.Xr stdc_trailing_zeros 3C , 122.Xr stdbit.h 3HEAD 123