---
name: "humanize_number"
section: "3"
platform: "linux"
package: "libbsd-dev"
version: "0.8.3-1"
release: "Debian 9 (Stretch)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/humanize_number"
---

# humanize\_number(3)

format a number into a human readable form and viceversa

## NAME

**dehumanize\_number**, **humanize\_number** – format a number into a human readable form and viceversa

## LIBRARY

library “libbsd”

## SYNOPSIS

**#include \<bsd/stdlib.h\>**

*int*\

**dehumanize\_number**(*const char \*str*, *int64\_t \*result*);

*int*\

**humanize\_number**(*char \*buf*, *size\_t len*, *int64\_t number*, *const char \*suffix*, *int scale*, *int flags*);

## DESCRIPTION

The **humanize\_number**() function formats the signed 64 bit quantity given in *number* into *buffer*. A space and then *suffix* is appended to the end. *buffer* must be at least *len* bytes long.

If the formatted number (including *suffix*) would be too long to fit into *buffer*, then divide *number* by 1024 until it will. In this case, prefix *suffix* with the appropriate SI designator.

The prefixes are:

| | | |
| --- | --- | --- |
| **Prefix** | **Description** | **Multiplier** |
| k kilo 1024 |
| M mega 1048576 |
| G giga 1073741824 |
| T tera 1099511627776 |
| P peta 1125899906842624 |
| E exa 1152921504606846976 |

*len* must be at least 4 plus the length of *suffix*, in order to ensure a useful result is generated into *buffer*. To use a specific prefix, specify this as *scale* (Multiplier = 1024 ^ scale). This can not be combined with any of the *scale* flags below.

The following flags may be passed in *scale*:

- HN\_AUTOSCALE

  Format the buffer using the lowest multiplier possible.

- HN\_GETSCALE

  Return the prefix index number (the number of times *number* must be divided to fit) instead of formatting it to the buffer.

The following flags may be passed in *flags*:

- HN\_DECIMAL

  If the final result is less than 10, display it using one digit.

- HN\_NOSPACE

  Do not put a space between *number* and the prefix.

- HN\_B

  Use 'B' (bytes) as prefix if the original result does not have a prefix.

- HN\_DIVISOR\_1000

  Divide *number* with 1000 instead of 1024.

The **dehumanize\_number**() function parses the string representing an integral value given in *str* and stores the numerical value in the integer pointed to by *result*. The provided string may hold one of the suffixes, which will be interpreted and used to scale up its accompanying numerical value.

## RETURN VALUES

**humanize\_number**() returns the number of characters stored in *buffer* (excluding the terminating NUL) upon success, or -1 upon failure. If HN\_GETSCALE is specified, the prefix index number will be returned instead.

**dehumanize\_number**() returns 0 if the string was parsed correctly. A -1 is returned to indicate failure and an error code is stored in *errno*.

## ERRORS

**dehumanize\_number**() will fail and no number will be stored in *result* if:

- \[EINVAL\]

  The string in *str* was empty or carried an unknown suffix.

- \[ERANGE\]

  The string in *str* represented a number that does not fit in *result*.

## SEE ALSO

humanize\_number(9)

## HISTORY

**humanize\_number**() first appeared in NetBSD 2.0.

**dehumanize\_number**() first appeared in NetBSD 5.0.