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