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