---
name: "humanize_number"
section: "3"
platform: "macos"
package: "libutil"
version: "73"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/humanize_number"
---

# humanize\_number(3)

format a number into a human readable form

## NAME

**humanize\_number** – format a number into a human readable form

## LIBRARY

System Utilities Library (libutil, -lutil)

## SYNOPSIS

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

*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 *buf*. A space and then *suffix* is appended to the end. The buffer pointed to by *buf* must be at least *len* bytes long.

If the formatted number (including *suffix*) would be too long to fit into *buf*, then divide *number* by 1024 until it will. In this case, prefix *suffix* with the appropriate designator. The **humanize\_number**() function follows the traditional computer science conventions by default, rather than the IEE/IEC (and now also SI) power of two convention or the power of ten notion. This behaviour however can be altered by specifying the HN\_DIVISOR\_1000 and HN\_IEC\_PREFIXES flags.

The traditional (default) prefixes are:

| | | | |
| --- | --- | --- | --- |
| **Prefix** | **Description** | **Multiplier** | **Multiplier 1000x** |
| (note) | kilo | 1024 | 1000 |
| M | mega | 1048576 | 1000000 |
| G | giga | 1073741824 | 1000000000 |
| T | tera | 1099511627776 | 1000000000000 |
| P | peta | 1125899906842624 | 1000000000000000 |
| E | exa | 1152921504606846976 | 1000000000000000000 |

Note: An uppercase K indicates a power of two, a lowercase k a power of ten.

The IEE/IEC (and now also SI) power of two prefixes are:

| | | |
| --- | --- | --- |
| **Prefix** | **Description** | **Multiplier** |
| Ki | kibi | 1024 |
| Mi | mebi | 1048576 |
| Gi | gibi | 1073741824 |
| Ti | tebi | 1099511627776 |
| Pi | pebi | 1125899906842624 |
| Ei | exbi | 1152921504606846976 |

The *len* argument must be at least 4 plus the length of *suffix*, in order to ensure a useful result is generated into *buf*. To use a specific prefix, specify this as *scale* (multiplier = 1024 ^ scale; when HN\_DIVISOR\_1000 is specified, multiplier = 1000 ^ scale). This cannot 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 decimal place.

- 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.

- HN\_IEC\_PREFIXES

  Use the IEE/IEC notion of prefixes (Ki, Mi, Gi...). This flag has no effect when HN\_DIVISOR\_1000 is also specified.

## RETURN VALUES

Upon success, the **humanize\_number** function returns the number of characters that would have been stored in *buf* (excluding the terminating NUL) if *buf* was large enough, or -1 upon failure. Even upon failure, the contents of *buf* may be modified. If HN\_GETSCALE is specified, the prefix index number will be returned instead.

## STANDARDS

The HN\_DIVISOR\_1000 and HN\_IEC\_PREFIXES flags conform to ISO/IEC Std 80000-13:2008 and IEEE Std 1541-2002.

## HISTORY

The **humanize\_number**() function first appeared in NetBSD 2.0 and then in FreeBSD 5.3. The HN\_IEC\_PREFIXES flag was introduced in FreeBSD 9.0.

## CAVEATS

For numbers greater than 999 using buffer length of 4 and less can cause rounding errors. When using HN\_IEC\_PREFIXES the same error occurs for buffer length of 5 or less.