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