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 July 25, 2025 28.Dt EXPAND_NUMBER 3 29.Os 30.Sh NAME 31.Nm expand_number 32.Nd parse a number from human readable form 33.Sh LIBRARY 34.Lb libutil 35.Sh SYNOPSIS 36.In libutil.h 37.Ft int 38.Fo expand_number 39.Fa "const char *buf" "int64_t *num" 40.Fc 41.Sh DESCRIPTION 42The 43.Fn expand_number 44function parses the number in the string pointed to by its 45.Fa buf 46argument and stores the number it represents as a signed 64-bit 47quantity in the location pointed to by its 48.Fa *num 49argument. 50.Pp 51The input string must consist of a decimal number, optionally preceded 52by a 53.Sq + 54or 55.Sq - 56sign, and optionally followed, without intervening whitespace, by a 57suffix indicating a power-of-two multiplier to apply. 58Any amount of whitespace at the beginning of the string will be 59ignored. 60.Pp 61Recognized suffixes are: 62.Bl -column "Suffix" "Description" "1000000000000000000" -offset indent 63.It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier" 64.It Li K Ta No kilo Ta 1,024 65.It Li M Ta No mega Ta 1,048,576 66.It Li G Ta No giga Ta 1,073,741,824 67.It Li T Ta No tera Ta 1,099,511,627,776 68.It Li P Ta No peta Ta 1,125,899,906,842,624 69.It Li E Ta No exa Ta 1,152,921,504,606,846,976 70.El 71.Pp 72For historical reasons, the 73.Fn expand_number 74function accepts and ignores a single 75.Dq B 76suffix at the end of the 77.Fa buf 78string (i.e. 79.Dq 5b 80is interpreted as 5, and 81.Dq 5kb 82is interpreted as 5,120). 83However, the usage of this suffix is discouraged. 84.Sh RETURN VALUES 85.Rv -std 86.Sh ERRORS 87The 88.Fn expand_number 89function will fail if: 90.Bl -tag -width Er 91.It Bq Er EINVAL 92The given string does not contain a valid number. 93.It Bq Er EINVAL 94An unrecognized suffix was encountered. 95.It Bq Er ERANGE 96The given string represents a number which does not fit into a 97.Vt int64_t . 98.El 99.Sh SEE ALSO 100.Xr humanize_number 3 101.Sh HISTORY 102The 103.Fn expand_number 104function first appeared in 105.Fx 6.3 . 106