lib/libutil/humanize_unsigned.3

   1 .\"     $NetBSD: humanize_number.9,v 1.9 2010/08/07 16:41:34 jruoho 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 November 3, 2010
  31 .Dt HUMANIZE_UNSIGNED 3
  32 .Os
  33 .Sh NAME
  34 .Nm humanize_unsigned ,
  35 .Nm format_bytes
  36 .Nd human readable numbers
  37 .Sh LIBRARY
  38 .Lb libutil
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In libutil.h
  42 .Ft int
  43 .Fn humanize_unsigned \
  44 "char *buf" "size_t len" "uint64_t number" "const char *suffix" "int divisor"
  45 .Ft int
  46 .Fn format_bytes "char *buf" "size_t len" "uint64_t number"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn humanize_unsigned
  50 function formats the unsigned 64-bit quantity given in
  51 .Fa number
  52 into
  53 .Fa buf .
  54 A space and then
  55 .Fa suffix
  56 is appended to the end.
  57 The supplied
  58 .Fa buf
  59 must be at least
  60 .Fa len
  61 bytes long.
  62 .Pp
  63 If the formatted number (including
  64 .Fa suffix )
  65 is too long to fit into
  66 .Fa buf ,
  67 .Fn humanize_unsigned
  68 divides
  69 .Fa number
  70 by
  71 .Fa divisor
  72 until it will fit.
  73 In this case,
  74 .Fa suffix
  75 is prefixed with the appropriate SI designator.
  76 Suitable values of
  77 .Fa divisor
  78 are 1024 or 1000 to remain consistent with the common meanings of the
  79 SI designator prefixes.
  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 k   kilo    1024
  85 .It M   mega    1048576
  86 .It G   giga    1073741824
  87 .It T   tera    1099511627776
  88 .It P   peta    1125899906842624
  89 .It E   exa     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 in
  97 .Fa buf .
  98 .Pp
  99 The
 100 .Fn format_bytes
 101 function
 102 is a front-end to
 103 .Fn humanize_unsigned .
 104 It calls the latter with a
 105 .Fa suffix
 106 of
 107 .Dq B .
 108 Also, if the suffix in the returned
 109 .Fa buf
 110 would not have a prefix, the suffix is removed.
 111 This means that a result of
 112 .Dq 100000
 113 occurs, instead of
 114 .Dq 100000 B .
 115 .Sh RETURN VALUES
 116 Both functions return the number of characters stored in
 117 .Fa buf
 118 (excluding the terminating NUL) upon success, or \-1 upon failure.
 119 .Sh SEE ALSO
 120 .Xr humanize_number 3
 121 .Sh HISTORY
 122 These functions first appeared in
 123 .Nx 1.5
 124 and were later ported to
 125 .Dx 2.9 .