FMT_SCALED(3) | Library Functions Manual | FMT_SCALED(3)

# NAME

`fmt_scaled`, `scan_scaled` — handle numbers with a human-readable scale

# SYNOPSIS

System Utilities Library (libutil, -lutil)
`#include <util.h>`

int
`scan_scaled`(char *number_w_scale, long long *result);

int
`fmt_scaled`(long long number, char *result);

# DESCRIPTION

The `scan_scaled`() function scans the given number and looks for a terminal scale multiplier of B, K, M, G, T, P or E (in either upper or lower case) for Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, Exabyte (computed using powers of two, i.e., Megabyte = 1024*1024). The number can have a decimal point, as in 1.5K, which returns 1536 (1024+512). If no scale factor is found, B is assumed.

The `fmt_scaled`() function formats a number for display using the same "human-readable" format, that is, a number with one of the above scale factors. Numbers will be printed with a maximum of four digits (preceded by a minus sign if the value is negative); values such as 0B, 100B, 1023B, 1K, 1.5K, 5.5M, and so on, will be generated. The "result" buffer must be allocated with at least `FMT_SCALED_STRSIZE` bytes. The result will be left-justified in the given space, and NUL-terminated.

# RETURN VALUES

The `scan_scaled`() and `fmt_scaled`() functions return 0 on success. In case of error, they return -1, leave *result as is, and set errno to one of the following values: `ERANGE` if the input string represents a number that is too large to represent. `EINVAL` if an unknown character was used as scale factor, or if the input to `scan_scaled`() was malformed, e.g., too many '.' characters.

# EXAMPLES

    char *cinput = "1.5K";
    long long result;
    if (scan_scaled(cinput, &result) == 0)
    	printf("%s -> %lld\n", cinput, result);
    else
    	fprintf(stderr, "%s - invalid\n", cinput);

    char buf[FMT_SCALED_STRSIZE];
    long long ninput = 10483892;
    if (fmt_scaled(ninput, buf) == 0)
    	printf("%lld -> %s\n", ninput, buf);
    else
    	fprintf(stderr, "fmt scaled failed (errno %d)", errno);

# SEE ALSO

printf(3), scanf(3)

# HISTORY

The functions `fmt_scaled`() and `scan_scaled`() first appeared in OpenBSD 3.4.

# AUTHORS

Ken Stailey wrote the first version of the code that became `fmt_scaled`(), originally inside OpenBSD df(1). Ian Darwin excerpted this and made it into a library routine (with significant help from Paul Janzen), and wrote `scan_scaled`().

# BUGS

Some of the scale factors have misleading meanings in lower case (p for P is incorrect; p should be pico- and P for Peta-). However, we bend the SI rules in favor of common sense here. A person creating a disk partition of "100m" is unlikely to require 100 millibytes (i.e., 0.1 byte) of storage in the partition; 100 megabytes is the only reasonable interpretation.

Cannot represent the larger scale factors on all architectures.

Ignores the current locale.

June 6, 2025 | Debian