lib/libutil/humanize_number.3

   1 .\"     $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $
   2 .\" $FreeBSD: head/lib/libutil/humanize_number.3 256130 2013-10-07 22:22:57Z jmg $
   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 May 5, 2018
  32 .Dt HUMANIZE_NUMBER 3
  33 .Os
  34 .Sh NAME
  35 .Nm dehumanize_number ,
  36 .Nm humanize_number
  37 .Nd format a number into a human readable form and vice versa
  38 .Sh LIBRARY
  39 .Lb libutil
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In libutil.h
  43 .Ft int
  44 .Fn dehumanize_number "const char *str" "int64_t *result"
  45 .Ft int
  46 .Fo humanize_number
  47 .Fa "char *buf" "size_t len" "int64_t number" "const char *suffix"
  48 .Fa "int scale" "int flags"
  49 .Fc
  50 .Sh DESCRIPTION
  51 The
  52 .Fn humanize_number
  53 function formats the signed 64-bit quantity given in
  54 .Fa number
  55 into
  56 .Fa buf .
  57 A space and then
  58 .Fa suffix
  59 is appended to the end.
  60 The buffer pointed to by
  61 .Fa buf
  62 must be at least
  63 .Fa len
  64 bytes long.
  65 .Pp
  66 If the formatted number (including
  67 .Fa suffix )
  68 would be too long to fit into
  69 .Fa buf ,
  70 then divide
  71 .Fa number
  72 by 1024 until it will.
  73 In this case, prefix
  74 .Fa suffix
  75 with the appropriate SI designator.
  76 The
  77 .Fn humanize_number
  78 function follows the traditional computer science conventions by
  79 default, rather than the IEE/IEC (and now also SI) power of two
  80 convention or the power of ten notion.
  81 This behaviour however can be altered by specifying the
  82 .Dv HN_DIVISOR_1000
  83 and
  84 .Dv HN_IEC_PREFIXES
  85 flags.
  86 .Pp
  87 The traditional
  88 .Pq default
  89 prefixes are:
  90 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
  91 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
  92 .It Li (note) Ta No kilo Ta 1024 Ta 1000
  93 .It Li M Ta No mega Ta 1048576 Ta 1000000
  94 .It Li G Ta No giga Ta 1073741824 Ta 1000000000
  95 .It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
  96 .It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
  97 .It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
  98 .El
  99 .Pp
 100 Note:
 101 An uppercase K indicates a power of two, a lowercase k a power of ten.
 102 .Pp
 103 The IEE/IEC (and now also SI) power of two prefixes are:
 104 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
 105 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
 106 .It Li Ki Ta No kibi Ta 1024
 107 .It Li Mi Ta No mebi Ta 1048576
 108 .It Li Gi Ta No gibi Ta 1073741824
 109 .It Li Ti Ta No tebi Ta 1099511627776
 110 .It Li Pi Ta No pebi Ta 1125899906842624
 111 .It Li Ei Ta No exbi Ta 1152921504606846976
 112 .El
 113 .Pp
 114 The
 115 .Fa len
 116 argument must be at least 4 plus the length of
 117 .Fa suffix ,
 118 in order to ensure a useful result is generated into
 119 .Fa buf .
 120 To use a specific prefix, specify this as
 121 .Fa scale
 122 .Po multiplier = 1024 ^ scale;
 123 when
 124 .Dv HN_DIVISOR_1000
 125 is specified,
 126 multiplier = 1000 ^ scale
 127 .Pc .
 128 This cannot be combined with any of the
 129 .Fa scale
 130 flags below.
 131 .Pp
 132 The following flags may be passed in
 133 .Fa scale :
 134 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 135 .It Dv HN_AUTOSCALE
 136 Format the buffer using the lowest multiplier possible.
 137 .It Dv HN_GETSCALE
 138 Return the prefix index number (the number of times
 139 .Fa number
 140 must be divided to fit) instead of formatting it to the buffer.
 141 .El
 142 .Pp
 143 The following flags may be passed in
 144 .Fa flags :
 145 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 146 .It Dv HN_FRACTIONAL
 147 Display up to two additional fractional digits if they would fit, unless
 148 the value was so small (i.e. less than 1000 or less than 1024) that it
 149 wouldn't make sense.
 150 .It Dv HN_DECIMAL
 151 If the final result is less than 10, display it using one decimal place.
 152 .It Dv HN_NOSPACE
 153 Do not put a space between
 154 .Fa number
 155 and the prefix.
 156 .It Dv HN_B
 157 Use
 158 .Ql B
 159 (bytes) as prefix if the original result does not have a prefix.
 160 .It Dv HN_DIVISOR_1000
 161 Divide
 162 .Fa number
 163 with 1000 instead of 1024.
 164 .It Dv HN_IEC_PREFIXES
 165 Use the IEE/IEC notion of prefixes (Ki, Mi, Gi...).
 166 This flag has no effect when
 167 .Dv HN_DIVISOR_1000
 168 is also specified.
 169 .El
 170 .Pp
 171 The
 172 .Fn dehumanize_number
 173 function parses the string representing an integral value given in
 174 .Fa str
 175 and stores the numerical value in the integer pointed to by
 176 .Fa result .
 177 The provided string may hold one of the suffixes, which will be interpreted
 178 and used to scale up its accompanying numerical value.
 179 .Sh RETURN VALUES
 180 Upon success, the
 181 .Fn humanize_number
 182 function returns the number of characters that would have been stored in
 183 .Fa buf
 184 (excluding the terminating
 185 .Dv NUL )
 186 if
 187 .Fa buf
 188 was large enough, or \-1 upon failure.
 189 Even upon failure, the contents of
 190 .Fa buf
 191 may be modified.
 192 If
 193 .Dv HN_GETSCALE
 194 is specified, the prefix index number will be returned instead.
 195 .Pp
 196 The
 197 .Fn dehumanize_number
 198 function returns 0 if the string was parsed correctly.
 199 A \-1 is returned to indicate failure and an error code is stored in
 200 .Va errno .
 201 .Sh ERRORS
 202 The
 203 .Fn dehumanize_number
 204 function will fail and no number will be stored in
 205 .Fa result
 206 if:
 207 .Bl -tag -width Er
 208 .It Bq Er EINVAL
 209 The string in
 210 .Fa str
 211 was empty or carried an unknown suffix.
 212 .It Bq Er ERANGE
 213 The string in
 214 .Fa str
 215 represented a number that does not fit in
 216 .Fa result .
 217 .El
 218 .Sh SEE ALSO
 219 .Xr strsuftoll 3 ,
 220 .Xr orders 7
 221 .Sh STANDARDS
 222 The
 223 .Dv HN_DIVISOR_1000
 224 and
 225 .Dv HN_IEC_PREFIXES
 226 flags
 227 conform to
 228 .Tn ISO/IEC
 229 Std\~80000-13:2008
 230 and
 231 .Tn IEEE
 232 Std\~1541-2002.
 233 .Sh HISTORY
 234 The
 235 .Fn humanize_number
 236 function first appeared in
 237 .Nx 2.0
 238 and then in
 239 .Fx 5.3 .
 240 The
 241 .Dv HN_IEC_PREFIXES
 242 flag was introduced in
 243 .Fx 9.0 .