Sat Aug 7 16:41:34 2010 UTC ()
Wording, markup.


(jruoho)
diff -r1.8 -r1.9 src/share/man/man9/humanize_number.9
cvs diff -r1.8 -r1.9 src/share/man/man9/humanize_number.9 (expand / switch to unified diff)

--- src/share/man/man9/humanize_number.9 2008/04/30 13:10:58 1.8
+++ src/share/man/man9/humanize_number.9 2010/08/07 16:41:34 1.9
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: humanize_number.9,v 1.8 2008/04/30 13:10:58 martin Exp $ 1.\" $NetBSD: humanize_number.9,v 1.9 2010/08/07 16:41:34 jruoho Exp $
2.\" 2.\"
3.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 3.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Luke Mewburn. 7.\" by Luke Mewburn.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -17,107 +17,103 @@ @@ -17,107 +17,103 @@
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd May 21, 1999 30.Dd August 7, 2010
31.Dt HUMANIZE_NUMBER 9 31.Dt HUMANIZE_NUMBER 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm humanize_number , 34.Nm humanize_number ,
35.Nm format_bytes 35.Nm format_bytes
36.Nd format a number into a human readable form 36.Nd human readable numbers
37.Sh SYNOPSIS 37.Sh SYNOPSIS
38.Ft int 38.Ft int
39.Fo humanize_number 39.Fn humanize_number \
40.Fa "char *buf" "size_t len" "uint64_t number" "const char *suffix" 40"char *buf" "size_t len" "uint64_t number" "const char *suffix" "int divisor"
41.Fa "int divisor" 
42.Fc 
43.Ft int 41.Ft int
44.Fn format_bytes "char *buf" "size_t len" "uint64_t number" 42.Fn format_bytes "char *buf" "size_t len" "uint64_t number"
45.Sh DESCRIPTION 43.Sh DESCRIPTION
46.Ss humanize_number 
47The 44The
48.Fn humanize_number 45.Fn humanize_number
49function formats the unsigned 64 bit quantity given in 46function formats the unsigned 64-bit quantity given in
50.Fa number 47.Fa number
51into 48into
52.Fa buffer . 49.Fa buf .
53A space and then 50A space and then
54.Fa suffix 51.Fa suffix
55is appended to the end. 52is appended to the end.
56.Fa buffer 53The supplied
 54.Fa buf
57must be at least 55must be at least
58.Fa len 56.Fa len
59bytes long. 57bytes long.
60.Pp 58.Pp
61If the formatted number (including 59If the formatted number (including
62.Fa suffix ) 60.Fa suffix )
63would be too long to fit into 61is too long to fit into
64.Fa buffer , 62.Fa buf ,
65then divide 63.Fn humanize_number
 64divides
66.Fa number 65.Fa number
67by 66by
68.Fa divisor 67.Fa divisor
69until it will. 68until it will fit.
70In this case, prefix 69In this case,
71.Fa suffix 70.Fa suffix
72with the appropriate SI designator. 71is prefixed with the appropriate SI designator.
73Suitable values of 72Suitable values of
74.Fa divisor 73.Fa divisor
75are 1024 or 1000 to remain consistent with the common meanings of the 74are 1024 or 1000 to remain consistent with the common meanings of the
76SI designator prefixes. 75SI designator prefixes.
77.Pp 76.Pp
78The prefixes are: 77The prefixes are:
79.Bl -column "Prefix" "Description" "Multiplier" -offset indent 78.Bl -column "Prefix" "Description" "Multiplier" -offset indent
80.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" 79.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
81.It k kilo 1024 80.It k kilo 1024
82.It M mega 1048576 81.It M mega 1048576
83.It G giga 1073741824 82.It G giga 1073741824
84.It T tera 1099511627776 83.It T tera 1099511627776
85.It P peta 1125899906842624 84.It P peta 1125899906842624
86.It E exa 1152921504606846976 85.It E exa 1152921504606846976
87.El 86.El
88.Pp 87.Pp
 88The
89.Fa len 89.Fa len
90must be at least 4 plus the length of 90argument must be at least 4 plus the length of
91.Fa suffix , 91.Fa suffix ,
92in order to ensure a useful result is generated into 92in order to ensure a useful result in
93.Fa buffer . 93.Fa buf .
94.Ss format_bytes 94.Pp
95The 95The
96.Fn format_bytes 96.Fn format_bytes
97function 97function
98is a front-end to 98is a front-end to
99.Fn humanize_number 99.Fn humanize_number .
100that calls the latter with a 100It calls the latter with a
101.Fa suffix 101.Fa suffix
102of 102of
103.Dq B . 103.Dq B .
104Also, if the suffix in the returned 104Also, if the suffix in the returned
105.Fa buffer 105.Fa buf
106would not have a prefix, remove the suffix. 106would not have a prefix, the suffix is removed.
107This means that a result of 107This means that a result of
108.Dq 100000 108.Dq 100000
109occurs, instead of 109occurs, instead of
110.Dq 100000 B . 110.Dq 100000 B .
111.Sh RETURN VALUES 111.Sh RETURN VALUES
112.Fn humanize_number 112Both functions return the number of characters stored in
113and 113.Fa buf
114.Fn format_bytes 
115return the number of characters stored in 
116.Fa buffer 
117(excluding the terminating NUL) upon success, or \-1 upon failure. 114(excluding the terminating NUL) upon success, or \-1 upon failure.
 115.Sh SEE ALSO
 116.Xr humanize_number 3
118.Sh HISTORY 117.Sh HISTORY
119.Fn humanize_number 118These functions first appeared in
120and 
121.Fn format_bytes 
122first appeared in 
123.Nx 1.5 . 119.Nx 1.5 .