MirOS Manual: fmt_scaled(3), scan_scaled(3)

FMT_SCALED(3)              BSD Programmer's 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 termi-
     nal 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

     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

           char *cinput = "1.5K";
           long long result;
           if (scan_scaled(cinput, &result) != 0)
                   printf("%s -> %ld\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 interpre-
     tation.

     Cannot represent the larger scale factors on all architectures.

     Ignores the current locale.

MirOS BSD #10-current         September 19, 2001                             1

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.