Add humanize_number(3) and split the trimdomain(3) function out from
[dragonfly.git] / 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 17: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 .