1.\" $NetBSD: humanize_number.9,v 1.5 2002/09/26 15:06:06 wiz Exp $ 2.\" 3.\" Copyright (c) 1999 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. 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 May 21, 1999 38.Dt HUMANIZE_NUMBER 9 39.Os 40.Sh NAME 41.Nm humanize_number , 42.Nm format_bytes 43.Nd format a number into a human readable form 44.Sh SYNOPSIS 45.Ft int 46.Fo humanize_number 47.Fa "char *buf" "size_t len" "u_int64_t number" "const char *suffix" 48.Fa "int divisor" 49.Fc 50.Ft int 51.Fn format_bytes "char *buf" "size_t len" "u_int64_t number" 52.Sh DESCRIPTION 53.Ss humanize_number 54The 55.Fn humanize_number 56function formats the unsigned 64 bit quantity given in 57.Fa number 58into 59.Fa buffer . 60A space and then 61.Fa suffix 62is appended to the end. 63.Fa buffer 64must be at least 65.Fa len 66bytes bytes long. 67.Pp 68If the formatted number (including 69.Fa suffix ) 70would be too long to fit into 71.Fa buffer , 72then divide 73.Fa number 74by 75.Fa divisor 76until it will. 77In this case, prefix 78.Fa suffix 79with the appropriate SI designator. 80Suitable values of 81.Fa divisor 82are 1024 or 1000 to remain consistent with the common meanings of the 83SI designator prefixes. 84.Pp 85The prefixes are: 86.Bl -column "Prefix" "Description" "Multiplier" -offset indent 87.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" 88.It k kilo 1024 89.It M mega 1048576 90.It G giga 1073741824 91.It T tera 1099511627776 92.It P peta 1125899906842624 93.It E exa 1152921504606846976 94.El 95.Pp 96.Fa len 97must be at least 4 plus the length of 98.Fa suffix , 99in order to ensure a useful result is generated into 100.Fa buffer . 101.Ss format_bytes 102The 103.Fn format_bytes 104function 105is a front-end to 106.Fn humanize_number 107that calls the latter with a 108.Fa suffix 109of 110.Dq B . 111Also, if the suffix in the returned 112.Fa buffer 113would not have a prefix, remove the suffix. 114This means that a result of 115.Dq 100000 116occurs, instead of 117.Dq 100000 B . 118.Sh RETURN VALUES 119.Fn humanize_number 120and 121.Fn format_bytes 122return the number of characters stored in 123.Fa buffer 124(excluding the terminating NUL) upon success, or \-1 upon failure. 125.Sh HISTORY 126.Fn humanize_number 127and 128.Fn format_bytes 129first appeared in 130.Nx 1.5 . 131