1.\" $NetBSD: humanize_number.3,v 1.3 2002/10/01 16:48:34 wiz Exp $ 2.\" 3.\" Copyright (c) 1999, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn and by Tomas Svensson. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 14, 2002 38.Dt HUMANIZE_NUMBER 3 39.Os 40.Sh NAME 41.Nm humanize_number 42.Nd format a number into a human readable form 43.Sh SYNOPSIS 44.Fd #include \*[Lt]util.h\*[Gt] 45.Ft int 46.Fn humanize_number "char *buf" "size_t len" "int64_t number" "const char *suffix" "int scale" "int flags" 47.Sh DESCRIPTION 48The 49.Fn humanize_number 50function formats the signed 64 bit quantity given in 51.Fa number 52into 53.Fa buffer . 54A space and then 55.Fa suffix 56is appended to the end. 57.Fa buffer 58must be at least 59.Fa len 60bytes bytes long. 61.Pp 62If the formatted number (including 63.Fa suffix ) 64would be too long to fit into 65.Fa buffer , 66then divide 67.Fa number 68by 1024 until it will. 69In this case, prefix 70.Fa suffix 71with the appropriate SI designator. 72.Pp 73The prefixes are: 74.Bl -column "Prefix" "Description" "Multiplier" -offset indent 75.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" 76.It k kilo 1024 77.It M mega 1048576 78.It G giga 1073741824 79.It T tera 1099511627776 80.It P peta 1125899906842624 81.It E exa 1152921504606846976 82.El 83.Pp 84.Fa len 85must be at least 4 plus the length of 86.Fa suffix , 87in order to ensure a useful result is generated into 88.Fa buffer . 89To use a specific prefix, specify this as 90.Fa scale 91(Multiplier = 1024 ^ scale). 92This can not be combined with any of the 93.Fa scale 94flags below. 95.Pp 96The following flags may be passed in 97.Pa scale : 98.Bl -tag -width Dv -offset indent 99.It Dv HN_AUTOSCALE 100Format the buffer using the lowest multiplier possible. 101.It Dv HN_GETSCALE 102Return the prefix index number (the number of times 103.Fa number 104must be divided to fit) instead of formatting it to the buffer. 105.El 106.Pp 107The following flags may be passed in 108.Pa flags : 109.Bl -tag -width Dv -offset indent 110.It Dv HN_DECIMAL 111If the final result is less than 10, display it using one digit. 112.It Dv HN_NOSPACE 113Do not put a space between 114.Fa number 115and the prefix. 116.It Dv HN_B 117Use 'B' (bytes) as prefix if the original result does not have a prefix. 118.It Dv HN_DIVISOR_1000 119Divide 120.Fa number 121with 1000 instead of 1024. 122.El 123.Sh RETURN VALUES 124.Fn humanize_number 125returns the number of characters stored in 126.Fa buffer 127(excluding the terminating NUL) upon success, or \-1 upon failure. 128If 129.Dv HN_GETSCALE 130is specified, the prefix index number will be returned instead. 131.Sh SEE ALSO 132.Xr humanize_number 9 133.Sh HISTORY 134.Fn humanize_number 135first appeared in 136.Nx 2.0 . 137