FMT_SCALED(3) | Library Functions Manual | FMT_SCALED(3) |
fmt_scaled
,
scan_scaled
— handle numbers
with a human-readable scale
#include
<util.h>
int
scan_scaled
(char
*number_w_scale, long
long *result);
int
fmt_scaled
(long
long number, char
*result);
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.
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.
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);
The functions fmt_scaled
() and
scan_scaled
() first appeared in
OpenBSD 3.4.
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
().
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.
July 16, 2016 | OpenBSD-6.9 |