xref: /dragonfly/lib/libutil/humanize_number.3 (revision 62e5eef5) 
1.\"	$NetBSD: humanize_number.3,v 1.5 2005/04/11 12:19:16 wiz Exp $
2.\" $FreeBSD: src/lib/libutil/humanize_number.3,v 1.12 2007/09/28 15:31:44 obrien Exp $
3.\" $DragonFly: src/lib/libutil/humanize_number.3,v 1.3 2008/08/04 19:42:39 swildner 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.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
24.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30.\" POSSIBILITY OF SUCH DAMAGE.
31.\"
32.Dd May 25, 2004
33.Dt HUMANIZE_NUMBER 3
34.Os
35.Sh NAME
36.Nm humanize_number
37.Nd format a number into a human readable form
38.Sh LIBRARY
39.Lb libutil
40.Sh SYNOPSIS
41.In libutil.h
42.Ft int
43.Fo humanize_number
44.Fa "char *buf" "size_t len" "int64_t number" "const char *suffix"
45.Fa "int scale" "int flags"
46.Fc
47.Sh DESCRIPTION
48The
49.Fn humanize_number
50function formats the signed 64-bit quantity given in
51.Fa number
52into
53.Fa buffer .
54A space and then
55.Fa suffix
56is appended to the end.
57The buffer pointed to by
58.Fa buffer
59must be at least
60.Fa len
61bytes long.
62.Pp
63If the formatted number (including
64.Fa suffix )
65would be too long to fit into
66.Fa buffer ,
67then divide
68.Fa number
69by 1024 until it will.
70In this case, prefix
71.Fa suffix
72with the appropriate SI designator.
73The
74.Fn humanize_number
75function
76follows the traditional computer science conventions rather than the proposed
77SI power of two convention.
78.Pp
79The prefixes are:
80.Bl -column "Prefix" "Description" "1000000000000000000" -offset indent
81.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" Ta Sy "Multiplier 1000x"
82.It Li k Ta No kilo Ta 1024 Ta 1000
83.It Li M Ta No mega Ta 1048576 Ta 1000000
84.It Li G Ta No giga Ta 1073741824 Ta 1000000000
85.It Li T Ta No tera Ta 1099511627776 Ta 1000000000000
86.It Li P Ta No peta Ta 1125899906842624 Ta 1000000000000000
87.It Li E Ta No exa Ta 1152921504606846976 Ta 1000000000000000000
88.El
89.Pp
90The
91.Fa len
92argument must be at least 4 plus the length of
93.Fa suffix ,
94in order to ensure a useful result is generated into
95.Fa buffer .
96To use a specific prefix, specify this as
97.Fa scale
98(multiplier = 1024 ^ scale).
99This cannot be combined with any of the
100.Fa scale
101flags below.
102.Pp
103The following flags may be passed in
104.Fa scale :
105.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
106.It Dv HN_AUTOSCALE
107Format the buffer using the lowest multiplier possible.
108.It Dv HN_GETSCALE
109Return the prefix index number (the number of times
110.Fa number
111must be divided to fit) instead of formatting it to the buffer.
112.El
113.Pp
114The following flags may be passed in
115.Fa flags :
116.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
117.It Dv HN_DECIMAL
118If the final result is less than 10, display it using one digit.
119.It Dv HN_NOSPACE
120Do not put a space between
121.Fa number
122and the prefix.
123.It Dv HN_B
124Use
125.Ql B
126(bytes) as prefix if the original result does not have a prefix.
127.It Dv HN_DIVISOR_1000
128Divide
129.Fa number
130with 1000 instead of 1024.
131.El
132.Sh RETURN VALUES
133The
134.Fn humanize_number
135function returns the number of characters stored in
136.Fa buffer
137(excluding the terminating
138.Dv NUL )
139upon success, or \-1 upon failure.
140If
141.Dv HN_GETSCALE
142is specified, the prefix index number will be returned instead.
143.Sh HISTORY
144The
145.Fn humanize_number
146function first appeared in
147.Nx 2.0
148and then in
149.Fx 5.3 .
150