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