Module Name: src
Committed By: jruoho
Date: Sat Aug 7 16:41:34 UTC 2010
Modified Files:
src/share/man/man9: humanize_number.9
Log Message:
Wording, markup.
To generate a diff of this commit:
cvs rdiff -u -r1.8 -r1.9 src/share/man/man9/humanize_number.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/humanize_number.9
diff -u src/share/man/man9/humanize_number.9:1.8 src/share/man/man9/humanize_number.9:1.9
--- src/share/man/man9/humanize_number.9:1.8 Wed Apr 30 13:10:58 2008
+++ src/share/man/man9/humanize_number.9 Sat Aug 7 16:41:34 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: humanize_number.9,v 1.8 2008/04/30 13:10:58 martin Exp $
+.\" $NetBSD: humanize_number.9,v 1.9 2010/08/07 16:41:34 jruoho Exp $
.\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,49 +27,48 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 21, 1999
+.Dd August 7, 2010
.Dt HUMANIZE_NUMBER 9
.Os
.Sh NAME
.Nm humanize_number ,
.Nm format_bytes
-.Nd format a number into a human readable form
+.Nd human readable numbers
.Sh SYNOPSIS
.Ft int
-.Fo humanize_number
-.Fa "char *buf" "size_t len" "uint64_t number" "const char *suffix"
-.Fa "int divisor"
-.Fc
+.Fn humanize_number \
+"char *buf" "size_t len" "uint64_t number" "const char *suffix" "int divisor"
.Ft int
.Fn format_bytes "char *buf" "size_t len" "uint64_t number"
.Sh DESCRIPTION
-.Ss humanize_number
The
.Fn humanize_number
-function formats the unsigned 64 bit quantity given in
+function formats the unsigned 64-bit quantity given in
.Fa number
into
-.Fa buffer .
+.Fa buf .
A space and then
.Fa suffix
is appended to the end.
-.Fa buffer
+The supplied
+.Fa buf
must be at least
.Fa len
bytes long.
.Pp
If the formatted number (including
.Fa suffix )
-would be too long to fit into
-.Fa buffer ,
-then divide
+is too long to fit into
+.Fa buf ,
+.Fn humanize_number
+divides
.Fa number
by
.Fa divisor
-until it will.
-In this case, prefix
+until it will fit.
+In this case,
.Fa suffix
-with the appropriate SI designator.
+is prefixed with the appropriate SI designator.
Suitable values of
.Fa divisor
are 1024 or 1000 to remain consistent with the common meanings of the
@@ -86,38 +85,35 @@
.It E exa 1152921504606846976
.El
.Pp
+The
.Fa len
-must be at least 4 plus the length of
+argument must be at least 4 plus the length of
.Fa suffix ,
-in order to ensure a useful result is generated into
-.Fa buffer .
-.Ss format_bytes
+in order to ensure a useful result in
+.Fa buf .
+.Pp
The
.Fn format_bytes
function
is a front-end to
-.Fn humanize_number
-that calls the latter with a
+.Fn humanize_number .
+It calls the latter with a
.Fa suffix
of
.Dq B .
Also, if the suffix in the returned
-.Fa buffer
-would not have a prefix, remove the suffix.
+.Fa buf
+would not have a prefix, the suffix is removed.
This means that a result of
.Dq 100000
occurs, instead of
.Dq 100000 B .
.Sh RETURN VALUES
-.Fn humanize_number
-and
-.Fn format_bytes
-return the number of characters stored in
-.Fa buffer
+Both functions return the number of characters stored in
+.Fa buf
(excluding the terminating NUL) upon success, or \-1 upon failure.
+.Sh SEE ALSO
+.Xr humanize_number 3
.Sh HISTORY
-.Fn humanize_number
-and
-.Fn format_bytes
-first appeared in
+These functions first appeared in
.Nx 1.5 .
