1.\" $OpenBSD: fmt_scaled.3,v 1.8 2016/07/16 16:10:44 jca 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 $Mdocdate: July 16 2016 $ 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.In 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 NUL-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 ERANGE 78if the input string represents a number that is too large to represent. 79.Dv EINVAL 80if an unknown character was used as scale factor, or 81if the input to 82.Fn scan_scaled 83was malformed, e.g., too many '.' characters. 84.Sh EXAMPLES 85.Bd -literal -offset indent 86char *cinput = "1.5K"; 87long long result; 88if (scan_scaled(cinput, &result) == 0) 89 printf("%s -> %lld\en", cinput, result); 90else 91 fprintf(stderr, "%s - invalid\en", cinput); 92 93char buf[FMT_SCALED_STRSIZE]; 94long long ninput = 10483892; 95if (fmt_scaled(ninput, buf) == 0) 96 printf("%lld -> %s\en", ninput, buf); 97else 98 fprintf(stderr, "fmt scaled failed (errno %d)", errno); 99.Ed 100.Sh SEE ALSO 101.Xr printf 3 , 102.Xr scanf 3 103.Sh HISTORY 104The functions 105.Fn fmt_scaled 106and 107.Fn scan_scaled 108first appeared in 109.Ox 3.4 . 110.Sh AUTHORS 111.An -nosplit 112.An Ken Stailey 113wrote the first version of the code that became 114.Fn fmt_scaled , 115originally inside 116.Ox 117.Xr df 1 . 118.An Ian Darwin 119excerpted this and made it into a library routine 120(with significant help from 121.An Paul Janzen ) , 122and wrote 123.Fn scan_scaled . 124.Sh BUGS 125Some of the scale factors have misleading meanings in lower case 126(p for P is incorrect; p should be pico- and P for Peta-). 127However, we bend the SI rules in favor of common sense here. 128A person creating a disk partition of "100m" is unlikely to require 129100 millibytes (i.e., 0.1 byte) of storage in the partition; 130100 megabytes is the only reasonable interpretation. 131.Pp 132Cannot represent the larger scale factors on all architectures. 133.Pp 134Ignores the current locale. 135