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 sys/types.h
  43 .In libutil.h
  44 .Ft int
  45 .Fn dehumanize_number "const char *str" "int64_t *result"
  46 .Ft int
  47 .Fo humanize_number
  48 .Fa "char *buf" "size_t len" "int64_t number" "const char *suffix"
  49 .Fa "int scale" "int flags"
  50 .Fc
  51 .Sh DESCRIPTION
  52 The
  53 .Fn humanize_number
  54 function formats the signed 64 bit quantity given in
  55 .Fa number
  56 into
  57 .Fa buffer .
  58 A space and then
  59 .Fa suffix
  60 is appended to the end.
  61 The buffer pointed to by
  62 .Fa buffer
  63 must be at least
  64 .Fa len
  65 bytes long.
  66 .Pp
  67 If the formatted number (including
  68 .Fa suffix )
  69 would be too long to fit into
  70 .Fa buffer ,
  71 then divide
  72 .Fa number
  73 by 1024 until it will.
  74 In this case, prefix
  75 .Fa suffix
  76 with the appropriate SI designator.
  77 The
  78 .Fn humanize_number
  79 function
  80 follows the traditional computer science conventions rather than the proposed
  81 SI power of two convention.
  82 .Pp
  83 The prefixes are:
  84 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
  85 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
  86 .It Li k Ta No kilo Ta 1024 Ta 1000
  87 .It Li M Ta No mega Ta 1048576 Ta 1000000
  88 .It Li G Ta No giga Ta 1073741824 Ta 1000000000
  89 .It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
  90 .It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
  91 .It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
  92 .El
  93 .Pp
  94 The
  95 .Fa len
  96 argument must be at least 4 plus the length of
  97 .Fa suffix ,
  98 in order to ensure a useful result is generated into
  99 .Fa buffer .
 100 To use a specific prefix, specify this as
 101 .Fa scale
 102 (multiplier = 1024 ^ scale).
 103 This cannot be combined with any of the
 104 .Fa scale
 105 flags below.
 106 .Pp
 107 The following flags may be passed in
 108 .Fa scale :
 109 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 110 .It Dv HN_AUTOSCALE
 111 Format the buffer using the lowest multiplier possible.
 112 .It Dv HN_GETSCALE
 113 Return the prefix index number (the number of times
 114 .Fa number
 115 must be divided to fit) instead of formatting it to the buffer.
 116 .El
 117 .Pp
 118 The following flags may be passed in
 119 .Fa flags :
 120 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 121 .It Dv HN_DECIMAL
 122 If the final result is less than 10, display it using one digit.
 123 .It Dv HN_NOSPACE
 124 Do not put a space between
 125 .Fa number
 126 and the prefix.
 127 .It Dv HN_B
 128 Use
 129 .Ql B
 130 (bytes) as prefix if the original result does not have a prefix.
 131 .It Dv HN_DIVISOR_1000
 132 Divide
 133 .Fa number
 134 with 1000 instead of 1024.
 135 .El
 136 .Pp
 137 The
 138 .Fn dehumanize_number
 139 function parses the string representing an integral value given in
 140 .Fa str
 141 and stores the numerical value in the integer pointed to by
 142 .Fa result .
 143 The provided string may hold one of the suffixes, which will be interpreted
 144 and used to scale up its accompanying numerical value.
 145 .Sh RETURN VALUES
 146 The
 147 .Fn humanize_number
 148 function returns the number of characters stored in
 149 .Fa buffer
 150 (excluding the terminating
 151 .Dv NUL )
 152 upon success, or \-1 upon failure.
 153 If
 154 .Dv HN_GETSCALE
 155 is specified, the prefix index number will be returned instead.
 156 .Pp
 157 The
 158 .Fn dehumanize_number
 159 function returns 0 if the string was parsed correctly.
 160 A \-1 is returned to indicate failure and an error code is stored in
 161 .Va errno .
 162 .Sh ERRORS
 163 The
 164 .Fn dehumanize_number
 165 function will fail and no number will be stored in
 166 .Fa result
 167 if:
 168 .Bl -tag -width Er
 169 .It Bq Er EINVAL
 170 The string in
 171 .Fa str
 172 was empty or carried an unknown suffix.
 173 .It Bq Er ERANGE
 174 The string in
 175 .Fa str
 176 represented a number that does not fit in
 177 .Fa result .
 178 .El
 179 .Sh HISTORY
 180 The
 181 .Fn humanize_number
 182 function first appeared in
 183 .Nx 2.0
 184 and then in
 185 .Fx 5.3 .
 186 .Pp
 187 The
 188 .Fn dehumanize_number
 189 function first appeared in
 190 .Nx 5.0 .