NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <util.h>

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

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

DESCRIPTION    [Toc]    [Back]

     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  null-terminated.

RETURN VALUES    [Toc]    [Back]

     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: EFAULT if an input pointer is NULL.
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    [Toc]    [Back]

           char *cinput = "1.5K";
           long long result;
           if (scan_scaled(cinput, &result) != 0)
                   printf("%s -> %ld0, cinput, result);
           else
                   fprintf(stderr, "%s - invalid0, cinput);

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

SEE ALSO    [Toc]    [Back]

     printf(3), scanf(3)

HISTORY    [Toc]    [Back]

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

AUTHORS    [Toc]    [Back]

     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    [Toc]    [Back]

     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.

OpenBSD     3.6                       September     19,      2001