lib/libutil/humanize_number.3

   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 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"        This product includes software developed by the NetBSD
  21 .\"        Foundation, Inc. and its contributors.
  22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  23 .\"    contributors may be used to endorse or promote products derived
  24 .\"    from this software without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .Dd Apr 12, 2011
  39 .Dt HUMANIZE_NUMBER 3
  40 .Os
  41 .Sh NAME
  42 .Nm humanize_number
  43 .Nd format a number into a human readable form
  44 .Sh LIBRARY
  45 .Lb libutil
  46 .Sh SYNOPSIS
  47 .In libutil.h
  48 .Ft int
  49 .Fo humanize_number
  50 .Fa "char *buf" "size_t len" "int64_t number" "const char *suffix"
  51 .Fa "int scale" "int flags"
  52 .Fc
  53 .Sh DESCRIPTION
  54 The
  55 .Fn humanize_number
  56 function formats the signed 64-bit quantity given in
  57 .Fa number
  58 into
  59 .Fa buf .
  60 A space and then
  61 .Fa suffix
  62 is appended to the end.
  63 The buffer pointed to by
  64 .Fa buf
  65 must be at least
  66 .Fa len
  67 bytes long.
  68 .Pp
  69 If the formatted number (including
  70 .Fa suffix )
  71 would be too long to fit into
  72 .Fa buf ,
  73 then divide
  74 .Fa number
  75 by 1024 until it will.
  76 In this case, prefix
  77 .Fa suffix
  78 with the appropriate designator.
  79 The
  80 .Fn humanize_number
  81 function follows the traditional computer science conventions by
  82 default, rather than the IEE/IEC (and now also SI) power of two
  83 convention or the power of ten notion.
  84 This behaviour however can be altered by specifying the
  85 .Dv HN_DIVISOR_1000
  86 and
  87 .Dv HN_IEC_PREFIXES
  88 flags.
  89 .Pp
  90 The traditional
  91 .Pq default
  92 prefixes are:
  93 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
  94 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
  95 .It Li (note) Ta No kilo Ta 1024 Ta 1000
  96 .It Li M Ta No mega Ta 1048576 Ta 1000000
  97 .It Li G Ta No giga Ta 1073741824 Ta 1000000000
  98 .It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
  99 .It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
 100 .It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
 101 .El
 102 .Pp
 103 Note:
 104 An uppercase K indicates a power of two, a lowercase k a power of ten.
 105 .Pp
 106 The IEE/IEC (and now also SI) power of two prefixes are:
 107 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
 108 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
 109 .It Li Ki Ta No kibi Ta 1024
 110 .It Li Mi Ta No mebi Ta 1048576
 111 .It Li Gi Ta No gibi Ta 1073741824
 112 .It Li Ti Ta No tebi Ta 1099511627776
 113 .It Li Pi Ta No pebi Ta 1125899906842624
 114 .It Li Ei Ta No exbi Ta 1152921504606846976
 115 .El
 116 .Pp
 117 The
 118 .Fa len
 119 argument must be at least 4 plus the length of
 120 .Fa suffix ,
 121 in order to ensure a useful result is generated into
 122 .Fa buf .
 123 To use a specific prefix, specify this as
 124 .Fa scale
 125 .Po multiplier = 1024 ^ scale;
 126 when
 127 .Dv HN_DIVISOR_1000
 128 is specified,
 129 multiplier = 1000 ^ scale
 130 .Pc .
 131 This cannot be combined with any of the
 132 .Fa scale
 133 flags below.
 134 .Pp
 135 The following flags may be passed in
 136 .Fa scale :
 137 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 138 .It Dv HN_AUTOSCALE
 139 Format the buffer using the lowest multiplier possible.
 140 .It Dv HN_GETSCALE
 141 Return the prefix index number (the number of times
 142 .Fa number
 143 must be divided to fit) instead of formatting it to the buffer.
 144 .El
 145 .Pp
 146 The following flags may be passed in
 147 .Fa flags :
 148 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 149 .It Dv HN_DECIMAL
 150 If the final result is less than 10, display it using one digit.
 151 .It Dv HN_NOSPACE
 152 Do not put a space between
 153 .Fa number
 154 and the prefix.
 155 .It Dv HN_B
 156 Use
 157 .Ql B
 158 (bytes) as prefix if the original result does not have a prefix.
 159 .It Dv HN_DIVISOR_1000
 160 Divide
 161 .Fa number
 162 with 1000 instead of 1024.
 163 .It Dv HN_IEC_PREFIXES
 164 Use the IEE/IEC notion of prefixes (Ki, Mi, Gi...).
 165 This flag has no effect when
 166 .Dv HN_DIVISOR_1000
 167 is also specified.
 168 .El
 169 .Sh RETURN VALUES
 170 The
 171 .Fn humanize_number
 172 function returns the number of characters stored in
 173 .Fa buf
 174 (excluding the terminating
 175 .Dv NUL )
 176 upon success, or \-1 upon failure.
 177 If
 178 .Dv HN_GETSCALE
 179 is specified, the prefix index number will be returned instead.
 180 .Sh SEE ALSO
 181 .Xr expand_number 3
 182 .Sh STANDARDS
 183 The
 184 .Dv HN_DIVISOR_1000
 185 and
 186 .Dv HN_IEC_PREFIXES
 187 flags
 188 conform to
 189 .Tn ISO/IEC
 190 Std\~80000-13:2008
 191 and
 192 .Tn IEEE
 193 Std\~1541-2002.
 194 .Sh HISTORY
 195 The
 196 .Fn humanize_number
 197 function first appeared in
 198 .Nx 2.0
 199 and then in
 200 .Fx 5.3 .
 201 The
 202 .Dv HN_IEC_PREFIXES
 203 flag was introduced in
 204 .Fx 9.0 .