l4/pkg/libbsd/lib/contrib/man/humanize_number.3

   1 .\"     $NetBSD: humanize_number.3,v 1.8 2008/04/30 13:10:50 martin 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 LIBRARY
  38 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
  39 .Lb libbsd
  40 .Sh SYNOPSIS
  41 .In bsd/stdlib.h
  42 .Ft int
  43 .Fn dehumanize_number "const char *str" "int64_t *result"
  44 .Ft int
  45 .Fn humanize_number "char *buf" "size_t len" "int64_t number" "const char *suffix" "int scale" "int flags"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn humanize_number
  49 function formats the signed 64 bit quantity given in
  50 .Fa number
  51 into
  52 .Fa buffer .
  53 A space and then
  54 .Fa suffix
  55 is appended to the end.
  56 .Fa buffer
  57 must be at least
  58 .Fa len
  59 bytes long.
  60 .Pp
  61 If the formatted number (including
  62 .Fa suffix )
  63 would be too long to fit into
  64 .Fa buffer ,
  65 then divide
  66 .Fa number
  67 by 1024 until it will.
  68 In this case, prefix
  69 .Fa suffix
  70 with the appropriate SI designator.
  71 .Pp
  72 The prefixes are:
  73 .Bl -column "Prefix" "Description" "Multiplier" -offset indent
  74 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
  75 .It k   kilo    1024
  76 .It M   mega    1048576
  77 .It G   giga    1073741824
  78 .It T   tera    1099511627776
  79 .It P   peta    1125899906842624
  80 .It E   exa     1152921504606846976
  81 .El
  82 .Pp
  83 .Fa len
  84 must be at least 4 plus the length of
  85 .Fa suffix ,
  86 in order to ensure a useful result is generated into
  87 .Fa buffer .
  88 To use a specific prefix, specify this as
  89 .Fa scale
  90 (Multiplier = 1024 ^ scale).
  91 This can not be combined with any of the
  92 .Fa scale
  93 flags below.
  94 .Pp
  95 The following flags may be passed in
  96 .Pa scale :
  97 .Bl -tag -width Dv -offset indent
  98 .It Dv HN_AUTOSCALE
  99 Format the buffer using the lowest multiplier possible.
 100 .It Dv HN_GETSCALE
 101 Return the prefix index number (the number of times
 102 .Fa number
 103 must be divided to fit) instead of formatting it to the buffer.
 104 .El
 105 .Pp
 106 The following flags may be passed in
 107 .Pa flags :
 108 .Bl -tag -width Dv -offset indent
 109 .It Dv HN_DECIMAL
 110 If the final result is less than 10, display it using one digit.
 111 .It Dv HN_NOSPACE
 112 Do not put a space between
 113 .Fa number
 114 and the prefix.
 115 .It Dv HN_B
 116 Use 'B' (bytes) as prefix if the original result does not have a prefix.
 117 .It Dv HN_DIVISOR_1000
 118 Divide
 119 .Fa number
 120 with 1000 instead of 1024.
 121 .El
 122 .Pp
 123 The
 124 .Fn dehumanize_number
 125 function parses the string representing an integral value given in
 126 .Fa str
 127 and stores the numerical value in the integer pointed to by
 128 .Fa result .
 129 The provided string may hold one of the suffixes, which will be interpreted
 130 and used to scale up its accompanying numerical value.
 131 .Sh RETURN VALUES
 132 .Fn humanize_number
 133 returns the number of characters stored in
 134 .Fa buffer
 135 (excluding the terminating NUL) upon success, or \-1 upon failure.
 136 If
 137 .Dv HN_GETSCALE
 138 is specified, the prefix index number will be returned instead.
 139 .Pp
 140 .Fn dehumanize_number
 141 returns 0 if the string was parsed correctly.
 142 A \-1 is returned to indicate failure and an error code is stored in
 143 .Va errno .
 144 .Sh ERRORS
 145 .Fn dehumanize_number
 146 will fail and no number will be stored in
 147 .Fa result
 148 if:
 149 .Bl -tag -width Er
 150 .It Bq Er EINVAL
 151 The string in
 152 .Fa str
 153 was empty or carried an unknown suffix.
 154 .It Bq Er ERANGE
 155 The string in
 156 .Fa str
 157 represented a number that does not fit in
 158 .Fa result .
 159 .El
 160 .Sh SEE ALSO
 161 .Xr humanize_number 9
 162 .Sh HISTORY
 163 .Fn humanize_number
 164 first appeared in
 165 .Nx 2.0 .
 166 .Pp
 167 .Fn dehumanize_number
 168 first appeared in
 169 .\" FIXME: This should be in groff, but for now it avoids the warning.
 170 .ds operating-system-NetBSD-5.0 5.0
 171 .Nx 5.0 .