lib/libutil/humanize_number.3

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