1.\" Copyright (c) 2007 Eric Anderson <anderson@FreeBSD.org> 2.\" Copyright (c) 2007 Pawel Jakub Dawidek <pjd@FreeBSD.org> 3.\" Copyright (c) 2025 Dag-Erling Smørgrav <des@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd August 6, 2025 28.Dt EXPAND_NUMBER 3 29.Os 30.Sh NAME 31.Nm expand_number , 32.Nm expand_unsigned 33.Nd parse a number from human readable form 34.Sh LIBRARY 35.Lb libutil 36.Sh SYNOPSIS 37.In libutil.h 38.Ft int 39.Fo expand_number 40.Fa "const char *buf" "int64_t *num" 41.Fc 42.Ft int 43.Fo expand_unsigned 44.Fa "const char *buf" "uint64_t *num" 45.Fc 46.Sh DESCRIPTION 47The 48.Fn expand_number 49function parses the number in the string pointed to by its 50.Fa buf 51argument and stores the number it represents as a signed 64-bit 52quantity in the location pointed to by its 53.Fa *num 54argument. 55.Pp 56The 57.Fn expand_unsigned 58function is similar to 59.Fn expand_number , 60but accepts only positive numbers in the range 61.Bq 0, Ns Dv UINT64_MAX . 62.Pp 63Both functions interpret the input 64.Dq -0 65as 0. 66.Pp 67The input string must consist of a decimal number, optionally preceded 68by a 69.Sq + 70or 71.Sq - 72sign, and optionally followed, without intervening whitespace, by a 73suffix indicating a power-of-two multiplier to apply. 74Any amount of whitespace at the beginning of the string will be 75ignored. 76.Pp 77Recognized suffixes are: 78.Bl -column "Suffix" "Description" "1000000000000000000" -offset indent 79.It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier" 80.It Li K Ta No kilo Ta 1,024 81.It Li M Ta No mega Ta 1,048,576 82.It Li G Ta No giga Ta 1,073,741,824 83.It Li T Ta No tera Ta 1,099,511,627,776 84.It Li P Ta No peta Ta 1,125,899,906,842,624 85.It Li E Ta No exa Ta 1,152,921,504,606,846,976 86.El 87.Pp 88For historical reasons, the 89.Fn expand_number 90function accepts and ignores a single 91.Dq B 92suffix at the end of the 93.Fa buf 94string (i.e. 95.Dq 5b 96is interpreted as 5, and 97.Dq 5kb 98is interpreted as 5,120). 99However, the usage of this suffix is discouraged. 100.Pp 101For backward compatibility reasons, if the compiler supports generic 102selection, a macro is provided which automatically replaces calls to 103.Fn expand_number 104with calls to 105.Fn expand_unsigned 106if the type of the actual 107.Va num 108argument is compatible with 109.Vt uint64_t * . 110.Sh RETURN VALUES 111.Rv -std 112.Sh ERRORS 113The 114.Fn expand_number 115and 116.Fn expand_unsigned 117functions will fail if: 118.Bl -tag -width Er 119.It Bq Er EINVAL 120The given string does not contain a valid number. 121.It Bq Er EINVAL 122An unrecognized suffix was encountered. 123.It Bq Er ERANGE 124The given string represents a number which does not fit into an 125.Vt int64_t 126(for 127.Fn expand_number ) 128or 129.Vt uint64_t 130(for 131.Fn expand_unsigned ) . 132.El 133.Sh SEE ALSO 134.Xr humanize_number 3 135.Sh HISTORY 136The 137.Fn expand_number 138function first appeared in 139.Fx 6.3 . 140The original implementation did not handle negative numbers correctly, 141and it was switched to taking a 142.Vt uint64_t * 143and accepting only positive numbers in 144.Fx 9.0 . 145The 146.Fn expand_unsigned 147function was added, 148and 149.Fn expand_number 150switched back to 151.Vt int64_t * , 152in 153.Fx 15.0 . 154