lib/libutil/humanize_number.3

   1 .\"     $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $
   2 .\" $FreeBSD$
   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 The
  80 .Fn humanize_number
  81 function
  82 follows the traditional computer science conventions rather than the proposed
  83 SI power of two convention.
  84 .Pp
  85 The prefixes are:
  86 .Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
  87 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
  88 .It Li k Ta No kilo Ta 1024 Ta 1000
  89 .It Li M Ta No mega Ta 1048576 Ta 1000000
  90 .It Li G Ta No giga Ta 1073741824 Ta 1000000000
  91 .It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
  92 .It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
  93 .It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
  94 .El
  95 .Pp
  96 The
  97 .Fa len
  98 argument must be at least 4 plus the length of
  99 .Fa suffix ,
 100 in order to ensure a useful result is generated into
 101 .Fa buffer .
 102 To use a specific prefix, specify this as
 103 .Fa scale
 104 (multiplier = 1024 ^ scale).
 105 This cannot be combined with any of the
 106 .Fa scale
 107 flags below.
 108 .Pp
 109 The following flags may be passed in
 110 .Fa scale :
 111 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 112 .It Dv HN_AUTOSCALE
 113 Format the buffer using the lowest multiplier possible.
 114 .It Dv HN_GETSCALE
 115 Return the prefix index number (the number of times
 116 .Fa number
 117 must be divided to fit) instead of formatting it to the buffer.
 118 .El
 119 .Pp
 120 The following flags may be passed in
 121 .Fa flags :
 122 .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
 123 .It Dv HN_DECIMAL
 124 If the final result is less than 10, display it using one digit.
 125 .It Dv HN_NOSPACE
 126 Do not put a space between
 127 .Fa number
 128 and the prefix.
 129 .It Dv HN_B
 130 Use
 131 .Ql B
 132 (bytes) as prefix if the original result does not have a prefix.
 133 .It Dv HN_DIVISOR_1000
 134 Divide
 135 .Fa number
 136 with 1000 instead of 1024.
 137 .El
 138 .Sh RETURN VALUES
 139 The
 140 .Fn humanize_number
 141 function returns the number of characters stored in
 142 .Fa buffer
 143 (excluding the terminating
 144 .Dv NUL )
 145 upon success, or \-1 upon failure.
 146 If
 147 .Dv HN_GETSCALE
 148 is specified, the prefix index number will be returned instead.
 149 .Sh SEE ALSO
 150 .Xr expand_number 3
 151 .Sh HISTORY
 152 The
 153 .Fn humanize_number
 154 function first appeared in
 155 .Nx 2.0
 156 and then in
 157 .Fx 5.3 .