humanize_number.3

   1 .\"     $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $
   2 .\" $FreeBSD: src/lib/libutil/humanize_number.3,v 1.8 2005/04/10 12:15:25 delphij Exp $
   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 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"        This product includes software developed by the NetBSD
  21 .\"        Foundation, Inc. and its contributors.
  22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  23 .\"    contributors may be used to endorse or promote products derived
  24 .\"    from this software without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .Dd May 25, 2004
  39 .Dt HUMANIZE_NUMBER 3
  40 .Os
  41 .Sh NAME
  42 .Nm humanize_number
  43 .Nd format a number into a human readable form
  44 .Sh LIBRARY
  45 .Lb libutil
  46 .Sh SYNOPSIS
  47 .In libutil.h
  48 .Ft int
  49 .Fo humanize_number
  50 .Fa "char *buf" "size_t len" "int64_t number" "const char *suffix"
  51 .Fa "int scale" "int flags"
  52 .Fc
  53 .Sh DESCRIPTION
  54 The
  55 .Fn humanize_number
  56 function formats the signed 64-bit quantity given in
  57 .Fa number
  58 into
  59 .Fa buffer .
  60 A space and then
  61 .Fa suffix
  62 is appended to the end.
  63 The buffer pointed to by
  64 .Fa buffer
  65 must be at least
  66 .Fa len
  67 bytes long.
  68 .Pp
  69 If the formatted number (including
  70 .Fa suffix )
  71 would be too long to fit into
  72 .Fa buffer ,
  73 then divide
  74 .Fa number
  75 by 1024 until it will.
  76 In this case, prefix
  77 .Fa suffix
  78 with the appropriate SI designator.
  79 .Pp
  80 The prefixes are:
  81 .Bl -column "Prefix" "Description" "Multiplier" -offset indent
  82 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
  83 .It Li k Ta No kilo Ta 1024
  84 .It Li M Ta No mega Ta 1048576
  85 .It Li G Ta No giga Ta 1073741824
  86 .It Li T Ta No tera Ta 1099511627776
  87 .It Li P Ta No peta Ta 1125899906842624
  88 .It Li E Ta No exa Ta 1152921504606846976
  89 .El
  90 .Pp
  91 The
  92 .Fa len
  93 argument must be at least 4 plus the length of
  94 .Fa suffix ,
  95 in order to ensure a useful result is generated into
  96 .Fa buffer .
  97 To use a specific prefix, specify this as
  98 .Fa scale
  99 (multiplier = 1024 ^ scale).
 100 This cannot be combined with any of the
 101 .Fa scale
 102 flags below.
 103 .Pp
 104 The following flags may be passed in
 105 .Fa scale :
 106 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 107 .It Dv HN_AUTOSCALE
 108 Format the buffer using the lowest multiplier possible.
 109 .It Dv HN_GETSCALE
 110 Return the prefix index number (the number of times
 111 .Fa number
 112 must be divided to fit) instead of formatting it to the buffer.
 113 .El
 114 .Pp
 115 The following flags may be passed in
 116 .Fa flags :
 117 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 118 .It Dv HN_DECIMAL
 119 If the final result is less than 10, display it using one digit.
 120 .It Dv HN_NOSPACE
 121 Do not put a space between
 122 .Fa number
 123 and the prefix.
 124 .It Dv HN_B
 125 Use
 126 .Ql B
 127 (bytes) as prefix if the original result does not have a prefix.
 128 .It Dv HN_DIVISOR_1000
 129 Divide
 130 .Fa number
 131 with 1000 instead of 1024.
 132 .El
 133 .Sh RETURN VALUES
 134 The
 135 .Fn humanize_number
 136 function returns the number of characters stored in
 137 .Fa buffer
 138 (excluding the terminating
 139 .Dv NUL )
 140 upon success, or \-1 upon failure.
 141 If
 142 .Dv HN_GETSCALE
 143 is specified, the prefix index number will be returned instead.
 144 .Sh HISTORY
 145 The
 146 .Fn humanize_number
 147 function first appeared in
 148 .Nx 2.0 .