1.\" $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 7, 2013 31.Dt HUMANIZE_NUMBER 3 32.Os 33.Sh NAME 34.Nm humanize_number 35.Nd format a number into a human readable form 36.Sh LIBRARY 37.Lb libutil 38.Sh SYNOPSIS 39.In libutil.h 40.Ft int 41.Fo humanize_number 42.Fa "char *buf" "size_t len" "int64_t number" "const char *suffix" 43.Fa "int scale" "int flags" 44.Fc 45.Sh DESCRIPTION 46The 47.Fn humanize_number 48function formats the signed 64-bit quantity given in 49.Fa number 50into 51.Fa buf . 52A space and then 53.Fa suffix 54is appended to the end. 55The buffer pointed to by 56.Fa buf 57must be at least 58.Fa len 59bytes long. 60.Pp 61If the formatted number (including 62.Fa suffix ) 63would be too long to fit into 64.Fa buf , 65then divide 66.Fa number 67by 1024 until it will. 68In this case, prefix 69.Fa suffix 70with the appropriate designator. 71The 72.Fn humanize_number 73function follows the traditional computer science conventions by 74default, rather than the IEE/IEC (and now also SI) power of two 75convention or the power of ten notion. 76This behaviour however can be altered by specifying the 77.Dv HN_DIVISOR_1000 78and 79.Dv HN_IEC_PREFIXES 80flags. 81.Pp 82The traditional 83.Pq default 84prefixes are: 85.Bl -column "Prefix" "Description" "1000000000000000000" -offset indent 86.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x" 87.It Li (note) Ta No kilo Ta 1024 Ta 1000 88.It Li M Ta No mega Ta 1048576 Ta 1000000 89.It Li G Ta No giga Ta 1073741824 Ta 1000000000 90.It Li T Ta No tera Ta 1099511627776 Ta 1000000000000 91.It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000 92.It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000 93.El 94.Pp 95Note: 96An uppercase K indicates a power of two, a lowercase k a power of ten. 97.Pp 98The IEE/IEC (and now also SI) power of two prefixes are: 99.Bl -column "Prefix" "Description" "1000000000000000000" -offset indent 100.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" 101.It Li Ki Ta No kibi Ta 1024 102.It Li Mi Ta No mebi Ta 1048576 103.It Li Gi Ta No gibi Ta 1073741824 104.It Li Ti Ta No tebi Ta 1099511627776 105.It Li Pi Ta No pebi Ta 1125899906842624 106.It Li Ei Ta No exbi Ta 1152921504606846976 107.El 108.Pp 109The 110.Fa len 111argument must be at least 4 plus the length of 112.Fa suffix , 113in order to ensure a useful result is generated into 114.Fa buf . 115To use a specific prefix, specify this as 116.Fa scale 117.Po multiplier = 1024 ^ scale; 118when 119.Dv HN_DIVISOR_1000 120is specified, 121multiplier = 1000 ^ scale 122.Pc . 123This cannot be combined with any of the 124.Fa scale 125flags below. 126.Pp 127The following flags may be passed in 128.Fa scale : 129.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent 130.It Dv HN_AUTOSCALE 131Format the buffer using the lowest multiplier possible. 132.It Dv HN_GETSCALE 133Return the prefix index number (the number of times 134.Fa number 135must be divided to fit) instead of formatting it to the buffer. 136.El 137.Pp 138The following flags may be passed in 139.Fa flags : 140.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent 141.It Dv HN_DECIMAL 142If the final result is less than 10, display it using one decimal place. 143.It Dv HN_NOSPACE 144Do not put a space between 145.Fa number 146and the prefix. 147.It Dv HN_B 148Use 149.Ql B 150(bytes) as prefix if the original result does not have a prefix. 151.It Dv HN_DIVISOR_1000 152Divide 153.Fa number 154with 1000 instead of 1024. 155.It Dv HN_IEC_PREFIXES 156Use the IEE/IEC notion of prefixes (Ki, Mi, Gi...). 157This flag has no effect when 158.Dv HN_DIVISOR_1000 159is also specified. 160.El 161.Sh RETURN VALUES 162Upon success, the 163.Nm 164function returns the number of characters that would have been stored in 165.Fa buf 166(excluding the terminating 167.Dv NUL ) 168if 169.Fa buf 170was large enough, or \-1 upon failure. 171Even upon failure, the contents of 172.Fa buf 173may be modified. 174If 175.Dv HN_GETSCALE 176is specified, the prefix index number will be returned instead. 177.Sh SEE ALSO 178.Xr expand_number 3 179.Sh STANDARDS 180The 181.Dv HN_DIVISOR_1000 182and 183.Dv HN_IEC_PREFIXES 184flags 185conform to ISO/IEC Std\~80000-13:2008 186and IEEE Std\~1541-2002. 187.Sh HISTORY 188The 189.Fn humanize_number 190function first appeared in 191.Nx 2.0 192and then in 193.Fx 5.3 . 194The 195.Dv HN_IEC_PREFIXES 196flag was introduced in 197.Fx 9.0 . 198.Sh CAVEATS 199For numbers greater than 999 using buffer length of 4 and less can cause 200rounding errors. 201When using 202.Dv HN_IEC_PREFIXES 203the same error occurs for buffer length of 5 or less. 204