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 | .\" 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 |
---|
54 | The |
---|
55 | .Fn humanize_number |
---|
56 | function formats the signed 64-bit quantity given in |
---|
57 | .Fa number |
---|
58 | into |
---|
59 | .Fa buffer . |
---|
60 | A space and then |
---|
61 | .Fa suffix |
---|
62 | is appended to the end. |
---|
63 | The buffer pointed to by |
---|
64 | .Fa buffer |
---|
65 | must be at least |
---|
66 | .Fa len |
---|
67 | bytes long. |
---|
68 | .Pp |
---|
69 | If the formatted number (including |
---|
70 | .Fa suffix ) |
---|
71 | would be too long to fit into |
---|
72 | .Fa buffer , |
---|
73 | then divide |
---|
74 | .Fa number |
---|
75 | by 1024 until it will. |
---|
76 | In this case, prefix |
---|
77 | .Fa suffix |
---|
78 | with the appropriate SI designator. |
---|
79 | The |
---|
80 | .Fn humanize_number |
---|
81 | function |
---|
82 | follows the traditional computer science conventions rather than the proposed |
---|
83 | SI power of two convention. |
---|
84 | .Pp |
---|
85 | The prefixes 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 k 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 |
---|
96 | The |
---|
97 | .Fa len |
---|
98 | argument must be at least 4 plus the length of |
---|
99 | .Fa suffix , |
---|
100 | in order to ensure a useful result is generated into |
---|
101 | .Fa buffer . |
---|
102 | To use a specific prefix, specify this as |
---|
103 | .Fa scale |
---|
104 | (multiplier = 1024 ^ scale). |
---|
105 | This cannot be combined with any of the |
---|
106 | .Fa scale |
---|
107 | flags below. |
---|
108 | .Pp |
---|
109 | The following flags may be passed in |
---|
110 | .Fa scale : |
---|
111 | .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent |
---|
112 | .It Dv HN_AUTOSCALE |
---|
113 | Format the buffer using the lowest multiplier possible. |
---|
114 | .It Dv HN_GETSCALE |
---|
115 | Return the prefix index number (the number of times |
---|
116 | .Fa number |
---|
117 | must be divided to fit) instead of formatting it to the buffer. |
---|
118 | .El |
---|
119 | .Pp |
---|
120 | The following flags may be passed in |
---|
121 | .Fa flags : |
---|
122 | .Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent |
---|
123 | .It Dv HN_DECIMAL |
---|
124 | If the final result is less than 10, display it using one digit. |
---|
125 | .It Dv HN_NOSPACE |
---|
126 | Do not put a space between |
---|
127 | .Fa number |
---|
128 | and the prefix. |
---|
129 | .It Dv HN_B |
---|
130 | Use |
---|
131 | .Ql B |
---|
132 | (bytes) as prefix if the original result does not have a prefix. |
---|
133 | .It Dv HN_DIVISOR_1000 |
---|
134 | Divide |
---|
135 | .Fa number |
---|
136 | with 1000 instead of 1024. |
---|
137 | .El |
---|
138 | .Sh RETURN VALUES |
---|
139 | The |
---|
140 | .Fn humanize_number |
---|
141 | function returns the number of characters stored in |
---|
142 | .Fa buffer |
---|
143 | (excluding the terminating |
---|
144 | .Dv NUL ) |
---|
145 | upon success, or \-1 upon failure. |
---|
146 | If |
---|
147 | .Dv HN_GETSCALE |
---|
148 | is specified, the prefix index number will be returned instead. |
---|
149 | .Sh SEE ALSO |
---|
150 | .Xr expand_number 3 |
---|
151 | .Sh HISTORY |
---|
152 | The |
---|
153 | .Fn humanize_number |
---|
154 | function first appeared in |
---|
155 | .Nx 2.0 |
---|
156 | and then in |
---|
157 | .Fx 5.3 . |
---|