lib/libc/gen/humanize_number.3

   1 .\"     $NetBSD: humanize_number.3,v 1.7 2008/02/09 09:09:04 jmmv Exp $
   2 .\"
   3 .\" Copyright (c) 1999, 2002, 2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn and by Tomas Svensson.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd February 9, 2008
  31 .Dt HUMANIZE_NUMBER 3
  32 .Os
  33 .Sh NAME
  34 .Nm dehumanize_number ,
  35 .Nm humanize_number
  36 .Nd format a number into a human readable form and viceversa
  37 .Sh SYNOPSIS
  38 .In stdlib.h
  39 .Ft int
  40 .Fn dehumanize_number "const char *str" "int64_t *result"
  41 .Ft int
  42 .Fn humanize_number "char *buf" "size_t len" "int64_t number" "const char *suffix" "int scale" "int flags"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn humanize_number
  46 function formats the signed 64 bit quantity given in
  47 .Fa number
  48 into
  49 .Fa buffer .
  50 A space and then
  51 .Fa suffix
  52 is appended to the end.
  53 .Fa buffer
  54 must be at least
  55 .Fa len
  56 bytes long.
  57 .Pp
  58 If the formatted number (including
  59 .Fa suffix )
  60 would be too long to fit into
  61 .Fa buffer ,
  62 then divide
  63 .Fa number
  64 by 1024 until it will.
  65 In this case, prefix
  66 .Fa suffix
  67 with the appropriate SI designator.
  68 .Pp
  69 The prefixes are:
  70 .Bl -column "Prefix" "Description" "Multiplier" -offset indent
  71 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
  72 .It k   kilo    1024
  73 .It M   mega    1048576
  74 .It G   giga    1073741824
  75 .It T   tera    1099511627776
  76 .It P   peta    1125899906842624
  77 .It E   exa     1152921504606846976
  78 .El
  79 .Pp
  80 .Fa len
  81 must be at least 4 plus the length of
  82 .Fa suffix ,
  83 in order to ensure a useful result is generated into
  84 .Fa buffer .
  85 To use a specific prefix, specify this as
  86 .Fa scale
  87 (Multiplier = 1024 ^ scale).
  88 This can not be combined with any of the
  89 .Fa scale
  90 flags below.
  91 .Pp
  92 The following flags may be passed in
  93 .Pa scale :
  94 .Bl -tag -width Dv -offset indent
  95 .It Dv HN_AUTOSCALE
  96 Format the buffer using the lowest multiplier possible.
  97 .It Dv HN_GETSCALE
  98 Return the prefix index number (the number of times
  99 .Fa number
 100 must be divided to fit) instead of formatting it to the buffer.
 101 .El
 102 .Pp
 103 The following flags may be passed in
 104 .Pa flags :
 105 .Bl -tag -width Dv -offset indent
 106 .It Dv HN_DECIMAL
 107 If the final result is less than 10, display it using one digit.
 108 .It Dv HN_NOSPACE
 109 Do not put a space between
 110 .Fa number
 111 and the prefix.
 112 .It Dv HN_B
 113 Use 'B' (bytes) as prefix if the original result does not have a prefix.
 114 .It Dv HN_DIVISOR_1000
 115 Divide
 116 .Fa number
 117 with 1000 instead of 1024.
 118 .El
 119 .Pp
 120 The
 121 .Fn dehumanize_number
 122 function parses the string representing an integral value given in
 123 .Fa str
 124 and stores the numerical value in the integer pointed to by
 125 .Fa result .
 126 The provided string may hold one of the suffixes, which will be interpreted
 127 and used to scale up its accompanying numerical value.
 128 .Sh RETURN VALUES
 129 .Fn humanize_number
 130 returns the number of characters stored in
 131 .Fa buffer
 132 (excluding the terminating NUL) upon success, or \-1 upon failure.
 133 If
 134 .Dv HN_GETSCALE
 135 is specified, the prefix index number will be returned instead.
 136 .Pp
 137 .Fn dehumanize_number
 138 returns 0 if the string was parsed correctly.
 139 A \-1 is returned to indicate failure and an error code is stored in
 140 .Va errno .
 141 .Sh ERRORS
 142 .Fn dehumanize_number
 143 will fail and no number will be stored in
 144 .Fa result
 145 if:
 146 .Bl -tag -width Er
 147 .It Bq Er EINVAL
 148 The string in
 149 .Fa str
 150 was empty or carried an unknown suffix.
 151 .It Bq Er ERANGE
 152 The string in
 153 .Fa str
 154 represented a number that does not fit in
 155 .Fa result .
 156 .El
 157 .Sh SEE ALSO
 158 .Xr humanize_number 9
 159 .Sh HISTORY
 160 .Fn humanize_number
 161 first appeared in
 162 .Nx 2.0 .
 163 .Pp
 164 .Fn dehumanize_number
 165 first appeared in
 166 .Nx 5.0 .