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