share/man/man9/humanize_number.9

   1 .\"     $NetBSD: humanize_number.9,v 1.7 2005/12/26 19:48:12 perry Exp $
   2 .\"
   3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd May 21, 1999
  31 .Dt HUMANIZE_NUMBER 9
  32 .Os
  33 .Sh NAME
  34 .Nm humanize_number ,
  35 .Nm format_bytes
  36 .Nd format a number into a human readable form
  37 .Sh SYNOPSIS
  38 .Ft int
  39 .Fo humanize_number
  40 .Fa "char *buf" "size_t len" "uint64_t number" "const char *suffix"
  41 .Fa "int divisor"
  42 .Fc
  43 .Ft int
  44 .Fn format_bytes "char *buf" "size_t len" "uint64_t number"
  45 .Sh DESCRIPTION
  46 .Ss humanize_number
  47 The
  48 .Fn humanize_number
  49 function formats the unsigned 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 .Fa buffer
  57 must be at least
  58 .Fa len
  59 bytes long.
  60 .Pp
  61 If the formatted number (including
  62 .Fa suffix )
  63 would be too long to fit into
  64 .Fa buffer ,
  65 then divide
  66 .Fa number
  67 by
  68 .Fa divisor
  69 until it will.
  70 In this case, prefix
  71 .Fa suffix
  72 with the appropriate SI designator.
  73 Suitable values of
  74 .Fa divisor
  75 are 1024 or 1000 to remain consistent with the common meanings of the
  76 SI designator prefixes.
  77 .Pp
  78 The prefixes are:
  79 .Bl -column "Prefix" "Description" "Multiplier" -offset indent
  80 .It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
  81 .It k   kilo    1024
  82 .It M   mega    1048576
  83 .It G   giga    1073741824
  84 .It T   tera    1099511627776
  85 .It P   peta    1125899906842624
  86 .It E   exa     1152921504606846976
  87 .El
  88 .Pp
  89 .Fa len
  90 must be at least 4 plus the length of
  91 .Fa suffix ,
  92 in order to ensure a useful result is generated into
  93 .Fa buffer .
  94 .Ss format_bytes
  95 The
  96 .Fn format_bytes
  97 function
  98 is a front-end to
  99 .Fn humanize_number
 100 that calls the latter with a
 101 .Fa suffix
 102 of
 103 .Dq B .
 104 Also, if the suffix in the returned
 105 .Fa buffer
 106 would not have a prefix, remove the suffix.
 107 This means that a result of
 108 .Dq 100000
 109 occurs, instead of
 110 .Dq 100000 B .
 111 .Sh RETURN VALUES
 112 .Fn humanize_number
 113 and
 114 .Fn format_bytes
 115 return the number of characters stored in
 116 .Fa buffer
 117 (excluding the terminating NUL) upon success, or \-1 upon failure.
 118 .Sh HISTORY
 119 .Fn humanize_number
 120 and
 121 .Fn format_bytes
 122 first appeared in
 123 .Nx 1.5 .