[src/trunk]: src/share/man/man9 add humanize_number(9) / format_bytes(9)

[lukem <lukem%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b51580b4989c
branches:  trunk
changeset: 473135:b51580b4989c
user:      lukem <lukem%NetBSD.org@localhost>
date:      Fri May 21 06:26:15 1999 +0000

description:
add humanize_number(9) / format_bytes(9)

diffstat:

 share/man/man9/Makefile          |   11 +-
 share/man/man9/humanize_number.9 |  126 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 5 deletions(-)

diffs (160 lines):

diff -r 44a629fe4d74 -r b51580b4989c share/man/man9/Makefile
--- a/share/man/man9/Makefile   Fri May 21 06:19:55 1999 +0000
+++ b/share/man/man9/Makefile   Fri May 21 06:26:15 1999 +0000
@@ -1,13 +1,13 @@
-#       $NetBSD: Makefile,v 1.51 1999/04/03 14:50:21 msaitoh Exp $
+#       $NetBSD: Makefile,v 1.52 1999/05/21 06:26:15 lukem Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
 MAN=   access.9 arp.9 audio.9 bus_space.9 bus_dma.9 copy.9 cpu_reboot.9 \
        ctxsw.9 disk.9 disklabel.9 doshutdownhooks.9 ethersubr.9 extent.9 \
-       fetch.9 fork1.9 inittodr.9 intro.9 ioctl.9 kprintf.9 log.9 malloc.9 mbuf.9 \
-       microtime.9 panic.9 pfil.9 physio.9 pool.9 psignal.9 resettodr.9 rnd.9 \
-       rt_timer.9 shutdownhook_establish.9 sleep.9 spl.9 store.9 time.9 \
-       timeout.9 uiomove.9 uvm.9 vslock.9 wdc.9
+       fetch.9 fork1.9 humanize_number.9 inittodr.9 intro.9 ioctl.9 kprintf.9 \
+       log.9 malloc.9 mbuf.9 microtime.9 panic.9 pfil.9 physio.9 pool.9 \
+       psignal.9 resettodr.9 rnd.9 rt_timer.9 shutdownhook_establish.9 \
+       sleep.9 spl.9 store.9 time.9 timeout.9 uiomove.9 uvm.9 vslock.9 wdc.9
 MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9
 MLINKS+=access.9 kernacc.9 access.9 useracc.9
 MLINKS+=bus_space.9 bus_space_alloc.9 bus_space.9 bus_space_barrier.9 \
@@ -67,6 +67,7 @@
        extent.9 extent_print.9
 MLINKS+=fetch.9 fubyte.9 fetch.9 fuibyte.9 fetch.9 fusword.9 \
        fetch.9 fuswintr.9 fetch.9 fuword.9 fetch.9 fuiword.9
+MLINKS+=humanize_number.9 format_bytes.9
 MLINKS+=kprintf.9 printf.9 kprintf.9 sprintf.9 kprintf.9 vprintf.9 \
        kprintf.9 uprintf.9 kprintf.9 ttyprintf.9
 MLINKS+=malloc.9 free.9
diff -r 44a629fe4d74 -r b51580b4989c share/man/man9/humanize_number.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/humanize_number.9  Fri May 21 06:26:15 1999 +0000
@@ -0,0 +1,126 @@
+.\"    $NetBSD: humanize_number.9,v 1.1 1999/05/21 06:26:15 lukem Exp $
+.\"
+.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Luke Mewburn.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 21, 1999
+.Dt HUMANIZE_NUMBER 9
+.Os
+.Sh NAME
+.Nm humanize_number ,
+.Nm format_bytes
+.Nd format a number into a human readable form.
+.Sh SYNOPSIS
+.Ft int
+.Fo humanize_number
+.Fa "char *buf" "size_t len" "u_int64_t number" "const char *suffix"
+.Fc
+.Ft int
+.Fn format_bytes "char *buf" "size_t len" "u_int64_t number"
+.Sh DESCRIPTION
+.Ss humanize_number
+.Pp
+The
+.Fn humanize_number
+function formats the unsigned 64 bit quantity given in
+.Fa number
+into
+.Fa buffer .
+A space and then
+.Fa suffix
+is appended to the end.
+.Fa buffer
+must be at least
+.Fa len
+bytes bytes long.
+.Pp
+If the formatted number (including
+.Fa suffix )
+would be too long to fit into
+.Fa buffer ,
+then divide
+.Fa number
+by 1024 until it will.
+In this case, prefix
+.Fa suffix
+with the appropriate SI designator.
+.Pp
+The prefixes are:
+.Bl -column "Prefix" "Description" "Multiplier" -offset indent
+.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
+.It K  kilo    1024
+.It M  mega    1048576
+.It G  giga    1073741824
+.It T  tera    1099511627776
+.It P  peta    1125899906842624
+.It E  exa     1152921504606846976
+.El
+.Pp
+.Fa len
+must be at least 4 plus the length of
+.Fa suffix ,
+in order to ensure a useful result is generated into
+.Fa buffer .
+.Pp
+.Ss format_bytes
+.Pp
+The
+.Fn format_bytes
+function
+is a front-end to
+.Fn humanize_number
+that 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.
+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
+(excluding the terminating NUL) upon success, or -1 upon failure.
+.Sh HISTORY
+.Fn humanize_number
+and
+.Fn format_bytes
+first appeared in
+.Nx 1.5 .