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