lib/libutil/humanize_number.3

   1 .\"     $NetBSD: humanize_number.3,v 1.5 2005/04/11 12:19:16 wiz Exp $
   2 .\" $FreeBSD: src/lib/libutil/humanize_number.3,v 1.12 2007/09/28 15:31:44 obrien Exp $
   3 .\" $DragonFly: src/lib/libutil/humanize_number.3,v 1.4 2008/09/14 20:04:59 swildner Exp $
   4 .\"
   5 .\" Copyright (c) 1999, 2002 The NetBSD Foundation, Inc.
   6 .\" All rights reserved.
   7 .\"
   8 .\" This code is derived from software contributed to The NetBSD Foundation
   9 .\" by Luke Mewburn and by Tomas Svensson.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  22 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  24 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  25 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  26 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30 .\" POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd September 14, 2008
  33 .Dt HUMANIZE_NUMBER 3
  34 .Os
  35 .Sh NAME
  36 .Nm dehumanize_number ,
  37 .Nm humanize_number
  38 .Nd format a number into a human readable form and vice versa
  39 .Sh LIBRARY
  40 .Lb libutil
  41 .Sh SYNOPSIS
  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 buffer .
  57 A space and then
  58 .Fa suffix
  59 is appended to the end.
  60 The buffer pointed to by
  61 .Fa buffer
  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 buffer ,
  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
  79 follows the traditional computer science conventions rather than the proposed
  80 SI power of two convention.
  81 .Pp
  82 The prefixes are:
  83 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
  84 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
  85 .It Li k Ta No kilo Ta 1024 Ta 1000
  86 .It Li M Ta No mega Ta 1048576 Ta 1000000
  87 .It Li G Ta No giga Ta 1073741824 Ta 1000000000
  88 .It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
  89 .It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
  90 .It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
  91 .El
  92 .Pp
  93 The
  94 .Fa len
  95 argument must be at least 4 plus the length of
  96 .Fa suffix ,
  97 in order to ensure a useful result is generated into
  98 .Fa buffer .
  99 To use a specific prefix, specify this as
 100 .Fa scale
 101 (multiplier = 1024 ^ scale).
 102 This cannot be combined with any of the
 103 .Fa scale
 104 flags below.
 105 .Pp
 106 The following flags may be passed in
 107 .Fa scale :
 108 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 109 .It Dv HN_AUTOSCALE
 110 Format the buffer using the lowest multiplier possible.
 111 .It Dv HN_GETSCALE
 112 Return the prefix index number (the number of times
 113 .Fa number
 114 must be divided to fit) instead of formatting it to the buffer.
 115 .El
 116 .Pp
 117 The following flags may be passed in
 118 .Fa flags :
 119 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 120 .It Dv HN_DECIMAL
 121 If the final result is less than 10, display it using one digit.
 122 .It Dv HN_NOSPACE
 123 Do not put a space between
 124 .Fa number
 125 and the prefix.
 126 .It Dv HN_B
 127 Use
 128 .Ql B
 129 (bytes) as prefix if the original result does not have a prefix.
 130 .It Dv HN_DIVISOR_1000
 131 Divide
 132 .Fa number
 133 with 1000 instead of 1024.
 134 .El
 135 .Pp
 136 The
 137 .Fn dehumanize_number
 138 function parses the string representing an integral value given in
 139 .Fa str
 140 and stores the numerical value in the integer pointed to by
 141 .Fa result .
 142 The provided string may hold one of the suffixes, which will be interpreted
 143 and used to scale up its accompanying numerical value.
 144 .Sh RETURN VALUES
 145 The
 146 .Fn humanize_number
 147 function returns the number of characters stored in
 148 .Fa buffer
 149 (excluding the terminating
 150 .Dv NUL )
 151 upon success, or \-1 upon failure.
 152 If
 153 .Dv HN_GETSCALE
 154 is specified, the prefix index number will be returned instead.
 155 .Pp
 156 The
 157 .Fn dehumanize_number
 158 function returns 0 if the string was parsed correctly.
 159 A \-1 is returned to indicate failure and an error code is stored in
 160 .Va errno .
 161 .Sh ERRORS
 162 The
 163 .Fn dehumanize_number
 164 function will fail and no number will be stored in
 165 .Fa result
 166 if:
 167 .Bl -tag -width Er
 168 .It Bq Er EINVAL
 169 The string in
 170 .Fa str
 171 was empty or carried an unknown suffix.
 172 .It Bq Er ERANGE
 173 The string in
 174 .Fa str
 175 represented a number that does not fit in
 176 .Fa result .
 177 .El
 178 .Sh HISTORY
 179 The
 180 .Fn humanize_number
 181 function first appeared in
 182 .Nx 2.0
 183 and then in
 184 .Fx 5.3 .
 185 .Pp
 186 The
 187 .Fn dehumanize_number
 188 function first appeared in
 189 .Nx 5.0 .