xref: /freebsd/lib/libutil/humanize_number.3 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
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.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29.\" POSSIBILITY OF SUCH DAMAGE.
30.\"
31.Dd October 7, 2013
32.Dt HUMANIZE_NUMBER 3
33.Os
34.Sh NAME
35.Nm humanize_number
36.Nd format a number into a human readable form
37.Sh LIBRARY
38.Lb libutil
39.Sh SYNOPSIS
40.In libutil.h
41.Ft int
42.Fo humanize_number
43.Fa "char *buf" "size_t len" "int64_t number" "const char *suffix"
44.Fa "int scale" "int flags"
45.Fc
46.Sh DESCRIPTION
47The
48.Fn humanize_number
49function formats the signed 64-bit quantity given in
50.Fa number
51into
52.Fa buf .
53A space and then
54.Fa suffix
55is appended to the end.
56The buffer pointed to by
57.Fa buf
58must be at least
59.Fa len
60bytes long.
61.Pp
62If the formatted number (including
63.Fa suffix )
64would be too long to fit into
65.Fa buf ,
66then divide
67.Fa number
68by 1024 until it will.
69In this case, prefix
70.Fa suffix
71with the appropriate designator.
72The
73.Fn humanize_number
74function follows the traditional computer science conventions by
75default, rather than the IEE/IEC (and now also SI) power of two
76convention or the power of ten notion.
77This behaviour however can be altered by specifying the
78.Dv HN_DIVISOR_1000
79and
80.Dv HN_IEC_PREFIXES
81flags.
82.Pp
83The traditional
84.Pq default
85prefixes are:
86.Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
87.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
88.It Li (note) Ta No kilo Ta 1024 Ta 1000
89.It Li M Ta No mega Ta 1048576 Ta 1000000
90.It Li G Ta No giga Ta 1073741824 Ta 1000000000
91.It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
92.It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
93.It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
94.El
95.Pp
96Note:
97An uppercase K indicates a power of two, a lowercase k a power of ten.
98.Pp
99The IEE/IEC (and now also SI) power of two prefixes are:
100.Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
101.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
102.It Li Ki Ta No kibi Ta 1024
103.It Li Mi Ta No mebi Ta 1048576
104.It Li Gi Ta No gibi Ta 1073741824
105.It Li Ti Ta No tebi Ta 1099511627776
106.It Li Pi Ta No pebi Ta 1125899906842624
107.It Li Ei Ta No exbi Ta 1152921504606846976
108.El
109.Pp
110The
111.Fa len
112argument must be at least 4 plus the length of
113.Fa suffix ,
114in order to ensure a useful result is generated into
115.Fa buf .
116To use a specific prefix, specify this as
117.Fa scale
118.Po multiplier = 1024 ^ scale;
119when
120.Dv HN_DIVISOR_1000
121is specified,
122multiplier = 1000 ^ scale
123.Pc .
124This cannot be combined with any of the
125.Fa scale
126flags below.
127.Pp
128The following flags may be passed in
129.Fa scale :
130.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
131.It Dv HN_AUTOSCALE
132Format the buffer using the lowest multiplier possible.
133.It Dv HN_GETSCALE
134Return the prefix index number (the number of times
135.Fa number
136must be divided to fit) instead of formatting it to the buffer.
137.El
138.Pp
139The following flags may be passed in
140.Fa flags :
141.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
142.It Dv HN_DECIMAL
143If the final result is less than 10, display it using one decimal place.
144.It Dv HN_NOSPACE
145Do not put a space between
146.Fa number
147and the prefix.
148.It Dv HN_B
149Use
150.Ql B
151(bytes) as prefix if the original result does not have a prefix.
152.It Dv HN_DIVISOR_1000
153Divide
154.Fa number
155with 1000 instead of 1024.
156.It Dv HN_IEC_PREFIXES
157Use the IEE/IEC notion of prefixes (Ki, Mi, Gi...).
158This flag has no effect when
159.Dv HN_DIVISOR_1000
160is also specified.
161.El
162.Sh RETURN VALUES
163Upon success, the
164.Nm
165function returns the number of characters that would have been stored in
166.Fa buf
167(excluding the terminating
168.Dv NUL )
169if
170.Fa buf
171was large enough, or \-1 upon failure.
172Even upon failure, the contents of
173.Fa buf
174may be modified.
175If
176.Dv HN_GETSCALE
177is specified, the prefix index number will be returned instead.
178.Sh SEE ALSO
179.Xr expand_number 3
180.Sh STANDARDS
181The
182.Dv HN_DIVISOR_1000
183and
184.Dv HN_IEC_PREFIXES
185flags
186conform to
187.Tn ISO/IEC
188Std\~80000-13:2008
189and
190.Tn IEEE
191Std\~1541-2002.
192.Sh HISTORY
193The
194.Fn humanize_number
195function first appeared in
196.Nx 2.0
197and then in
198.Fx 5.3 .
199The
200.Dv HN_IEC_PREFIXES
201flag was introduced in
202.Fx 9.0 .
203.Sh CAVEATS
204For numbers greater than 999 using buffer length of 4 and less can cause
205rounding errors.
206When using
207.Dv HN_IEC_PREFIXES
208the same error occurs for buffer length of 5 or less.
209