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 October 7, 2013
  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_DECIMAL
 147 If the final result is less than 10, display it using one decimal place.
 148 .It Dv HN_NOSPACE
 149 Do not put a space between
 150 .Fa number
 151 and the prefix.
 152 .It Dv HN_B
 153 Use
 154 .Ql B
 155 (bytes) as prefix if the original result does not have a prefix.
 156 .It Dv HN_DIVISOR_1000
 157 Divide
 158 .Fa number
 159 with 1000 instead of 1024.
 160 .It Dv HN_IEC_PREFIXES
 161 Use the IEE/IEC notion of prefixes (Ki, Mi, Gi...).
 162 This flag has no effect when
 163 .Dv HN_DIVISOR_1000
 164 is also specified.
 165 .El
 166 .Pp
 167 The
 168 .Fn dehumanize_number
 169 function parses the string representing an integral value given in
 170 .Fa str
 171 and stores the numerical value in the integer pointed to by
 172 .Fa result .
 173 The provided string may hold one of the suffixes, which will be interpreted
 174 and used to scale up its accompanying numerical value.
 175 .Sh RETURN VALUES
 176 Upon success, the
 177 .Fn humanize_number
 178 function returns the number of characters that would have been stored in
 179 .Fa buf
 180 (excluding the terminating
 181 .Dv NUL )
 182 if
 183 .Fa buf
 184 was large enough, or \-1 upon failure.
 185 Even upon failure, the contents of
 186 .Fa buf
 187 may be modified.
 188 If
 189 .Dv HN_GETSCALE
 190 is specified, the prefix index number will be returned instead.
 191 .Pp
 192 The
 193 .Fn dehumanize_number
 194 function returns 0 if the string was parsed correctly.
 195 A \-1 is returned to indicate failure and an error code is stored in
 196 .Va errno .
 197 .Sh ERRORS
 198 The
 199 .Fn dehumanize_number
 200 function will fail and no number will be stored in
 201 .Fa result
 202 if:
 203 .Bl -tag -width Er
 204 .It Bq Er EINVAL
 205 The string in
 206 .Fa str
 207 was empty or carried an unknown suffix.
 208 .It Bq Er ERANGE
 209 The string in
 210 .Fa str
 211 represented a number that does not fit in
 212 .Fa result .
 213 .El
 214 .Sh STANDARDS
 215 The
 216 .Dv HN_DIVISOR_1000
 217 and
 218 .Dv HN_IEC_PREFIXES
 219 flags
 220 conform to
 221 .Tn ISO/IEC
 222 Std\~80000-13:2008
 223 and
 224 .Tn IEEE
 225 Std\~1541-2002.
 226 .Sh HISTORY
 227 The
 228 .Fn humanize_number
 229 function first appeared in
 230 .Nx 2.0
 231 and then in
 232 .Fx 5.3 .
 233 The
 234 .Dv HN_IEC_PREFIXES
 235 flag was introduced in
 236 .Fx 9.0 .