---
name: "expand_number"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/expand_number"
---

# expand\_number(3)

parse a number from human readable form

## NAME

**expand\_number**, **expand\_unsigned** – parse a number from human readable form

## LIBRARY

System Utilities Library (libutil, -lutil)

## SYNOPSIS

**#include \<libutil.h\>**

*int*\

**expand\_number**(*const char \*buf*, *int64\_t \*num*);

*int*\

**expand\_unsigned**(*const char \*buf*, *uint64\_t \*num*);

## DESCRIPTION

The **expand\_number**() function parses the number in the string pointed to by its *buf* argument and stores the number it represents as a signed 64-bit quantity in the location pointed to by its *\*num* argument.

The **expand\_unsigned**() function is similar to **expand\_number**(), but accepts only positive numbers in the range \[0,UINT64\_MAX\].

Both functions interpret the input “-0” as 0.

The input string must consist of a decimal number, optionally preceded by a ‘+’ or ‘-’ sign, and optionally followed, without intervening whitespace, by a suffix indicating a power-of-two multiplier to apply. Any amount of whitespace at the beginning of the string will be ignored.

Recognized suffixes are:

| | | |
| --- | --- | --- |
| **Suffix** | **Description** | **Multiplier** |
| K | kilo | 1,024 |
| M | mega | 1,048,576 |
| G | giga | 1,073,741,824 |
| T | tera | 1,099,511,627,776 |
| P | peta | 1,125,899,906,842,624 |
| E | exa | 1,152,921,504,606,846,976 |

For historical reasons, the **expand\_number**() function accepts and ignores a single “B” suffix at the end of the *buf* string (i.e. “5b” is interpreted as 5, and “5kb” is interpreted as 5,120). However, the usage of this suffix is discouraged.

For backward compatibility reasons, if the compiler supports generic selection, a macro is provided which automatically replaces calls to **expand\_number**() with calls to **expand\_unsigned**() if the type of the actual *num* argument is compatible with *uint64\_t* *\**.

## RETURN VALUES

The **expand\_number()** function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

## ERRORS

The **expand\_number**() and **expand\_unsigned**() functions will fail if:

- \[EINVAL\]

  The given string does not contain a valid number.

- \[EINVAL\]

  An unrecognized suffix was encountered.

- \[ERANGE\]

  The given string represents a number which does not fit into an *int64\_t* (for **expand\_number**()) or *uint64\_t* (for **expand\_unsigned**()).

## SEE ALSO

[humanize\_number(3)](/humanize_number/3.md)

## HISTORY

The **expand\_number**() function first appeared in FreeBSD 6.3. The original implementation did not handle negative numbers correctly, and it was switched to taking a *uint64\_t* *\** and accepting only positive numbers in FreeBSD 9.0. The **expand\_unsigned**() function was added, and **expand\_number**() switched back to *int64\_t* *\**, in FreeBSD 15.0.