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