1.\" $NetBSD: humanize_number.9,v 1.3 2001/06/05 12:56:56 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 54.Pp 55The 56.Fn humanize_number 57function formats the unsigned 64 bit quantity given in 58.Fa number 59into 60.Fa buffer . 61A space and then 62.Fa suffix 63is appended to the end. 64.Fa buffer 65must be at least 66.Fa len 67bytes bytes long. 68.Pp 69If the formatted number (including 70.Fa suffix ) 71would be too long to fit into 72.Fa buffer , 73then divide 74.Fa number 75by 76.Fa divisor 77until it will. 78In this case, prefix 79.Fa suffix 80with the appropriate SI designator. 81Suitable values of 82.Fa divisor 83are 1024 or 1000 to remain consistent with the common meanings of the 84SI designator prefixes. 85.Pp 86The prefixes are: 87.Bl -column "Prefix" "Description" "Multiplier" -offset indent 88.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" 89.It K kilo 1024 90.It M mega 1048576 91.It G giga 1073741824 92.It T tera 1099511627776 93.It P peta 1125899906842624 94.It E exa 1152921504606846976 95.El 96.Pp 97.Fa len 98must be at least 4 plus the length of 99.Fa suffix , 100in order to ensure a useful result is generated into 101.Fa buffer . 102.Pp 103.Ss format_bytes 104.Pp 105The 106.Fn format_bytes 107function 108is a front-end to 109.Fn humanize_number 110that calls the latter with a 111.Fa suffix 112of 113.Dq B . 114Also, if the suffix in the returned 115.Fa buffer 116would not have a prefix, remove the suffix. 117This means that a result of 118.Dq 100000 119occurs, instead of 120.Dq 100000 B . 121.Sh RETURN VALUES 122.Fn humanize_number 123and 124.Fn format_bytes 125return the number of characters stored in 126.Fa buffer 127(excluding the terminating NUL) upon success, or -1 upon failure. 128.Sh HISTORY 129.Fn humanize_number 130and 131.Fn format_bytes 132first appeared in 133.Nx 1.5 . 134