| FMT_SCALED(3) |
AerieBSD 1.0 Refernce Manual |
FMT_SCALED(3) |
NAME
fmt_scaled —
scan_scaled
handle numbers with a human-readable scale
SYNOPSIS
#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 -> %ld\en", cinput, result);
else
fprintf(stderr, "%s - invalid\en", cinput);
char buf[FMT_SCALED_STRSIZE];
long long ninput = 10483892;
if (fmt_scaled(ninput, buf) == 0)
printf("%lld -> %s\en", 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.
| AerieBSD 1.0 Reference Manual |
December 26 2008 |
FMT_SCALED(3) |