February 9, 2008 HUMANIZE_NUMBER 3

### NAME

dehumanize_number, humanize_number - format a number into a human readable form and viceversa

### SYNOPSIS

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

dehumanize_number(``) first appeared in NetBSD5.0.