1.\" $OpenBSD: fmt_scaled.3,v 1.2 2003/06/02 11:37:27 jmc Exp $ 2.\" Copyright (c) 2001, 2003 Ian Darwin. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. The name of the author may not be used to endorse or promote products 13.\" derived from this software without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd September 19, 2001 27.Dt FMT_SCALED 3 28.Os 29.Sh NAME 30.Nm fmt_scaled , 31.Nm scan_scaled 32.Nd handle numbers with a human-readable scale 33.Sh SYNOPSIS 34.Fd #include <util.h> 35.Ft int 36.Fn scan_scaled "char *number_w_scale" "long long *result" 37.Ft int 38.Fn fmt_scaled "long long number" "char *result" 39.Sh DESCRIPTION 40The 41.Fn scan_scaled 42function scans the given number and looks for a terminal scale multiplier 43of B, K, M, G, T, P or E 44.Pq in either upper or lower case 45for Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, Exabyte 46.Po computed using powers of two, i.e., Megabyte = 1024*1024 47.Pc . 48The number can have a decimal point, as in 1.5K, which returns 1536 49.Pq 1024+512 . 50If no scale factor is found, B is assumed. 51.Pp 52The 53.Fn fmt_scaled 54function formats a number for display using the same 55"human-readable" format, that is, a number with one of the above scale factors. 56Numbers will be printed with a maximum of four digits (preceded by 57a minus sign if the value is negative); values such 58as 0B, 100B, 1023B, 1K, 1.5K, 5.5M, and so on, will be generated. 59The 60.Qq result 61buffer must be allocated with at least 62.Dv FMT_SCALED_STRSIZE 63bytes. 64The result will be left-justified in the given space, and null-terminated. 65.Sh RETURN VALUES 66The 67.Fn scan_scaled 68and 69.Fn fmt_scaled 70functions 71return 0 on success. 72In case of error, they return \-1, leave 73.Va *result 74as is, and set 75.Va errno 76to one of the following values: 77.Dv EFAULT 78if an input pointer is 79.Dv NULL . 80.Dv ERANGE 81if the input string represents a number that is too large to represent. 82.Dv EINVAL 83if an unknown character was used as scale factor, or 84if the input to 85.Fn scan_scaled 86was malformed, e.g., too many '.' characters. 87.Sh EXAMPLES 88.Bd -literal -offset indent 89char *cinput = "1.5K"; 90long long result; 91if (scan_scaled(cinput, &result) != 0) 92 printf("%s -> %ld\en", cinput, result); 93else 94 fprintf(stderr, "%s - invalid\en", cinput); 95 96char buf[FMT_SCALED_STRSIZE]; 97long long ninput = 10483892; 98if (fmt_scaled(ninput, buf) == 0) 99 printf("%lld -> %s\en", ninput, buf); 100else 101 fprintf(stderr, "fmt scaled failed (errno %d)", errno); 102.Ed 103.Sh SEE ALSO 104.Xr printf 3 , 105.Xr scanf 3 106.Sh HISTORY 107The functions 108.Fn fmt_scaled 109and 110.Fn scan_scaled 111first appeared in 112.Ox 3.4 . 113.Sh AUTHORS 114Ken Stailey wrote the first version of the code that became 115.Fn fmt_scaled , 116originally inside 117.Ox 118.Xr df 1 . 119Ian Darwin excerpted this and made it into a library routine 120(with significant help from Paul Janzen), and wrote 121.Fn scan_scaled . 122.Sh BUGS 123Some of the scale factors have misleading meanings in lower case 124(p for P is incorrect; p should be pico- and P for Peta-). 125However, we bend the SI rules in favor of common sense here. 126A person creating a disk partition of "100m" is unlikely to require 127100 millibytes (i.e., 0.1 byte) of storage in the partition; 128100 megabytes is the only reasonable interpretation. 129.Pp 130Cannot represent the larger scale factors on all architectures. 131.Pp 132Ignores the current locale. 133