May 21, 1999 HUMANIZE_NUMBER 9

### NAME

humanize_number, format_bytes - format a number into a human readable form

### SYNOPSIS

```int` humanize_number(`` ```char *buf` `size_t len` `uint64_t number` `const char *suffix` ```int divisor` )
```int` format_bytes(```char *buf``, size_t len``, uint64_t number`)

### DESCRIPTION

#### humanize_number

The humanize_number(``) function formats the unsigned 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 ```divisor` until it will. In this case, prefix ```suffix` with the appropriate SI designator. Suitable values of ```divisor` are 1024 or 1000 to remain consistent with the common meanings of the SI designator prefixes.

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

#### format_bytes

The format_bytes(``) function is a front-end to humanize_number(``) that calls the latter with a ```suffix` of ``B''. Also, if the suffix in the returned ```buffer` would not have a prefix, remove the suffix. This means that a result of ``100000'' occurs, instead of ``100000 B''.

### RETURN VALUES

humanize_number(``) and format_bytes(``) return the number of characters stored in ```buffer` (excluding the terminating NUL) upon success, or -1 upon failure.

### HISTORY

humanize_number(``) and format_bytes(``) first appeared in NetBSD1.5.