diff options
author | pjd <pjd@FreeBSD.org> | 2004-05-24 22:19:27 +0000 |
---|---|---|
committer | pjd <pjd@FreeBSD.org> | 2004-05-24 22:19:27 +0000 |
commit | d207894810cf9fa574c3f60f611210946e00a166 (patch) | |
tree | 32c833de9efdb9ee45b5a114068632de7a8d073d /lib/libutil/humanize_number.3 | |
parent | 06701a2fa969f461f476522609e94f065fb97e0e (diff) | |
download | FreeBSD-src-d207894810cf9fa574c3f60f611210946e00a166.zip FreeBSD-src-d207894810cf9fa574c3f60f611210946e00a166.tar.gz |
Add humanize_number(3) to libutil for formating numbers into a human
readable form.
Obtained from: NetBSD
Diffstat (limited to 'lib/libutil/humanize_number.3')
-rw-r--r-- | lib/libutil/humanize_number.3 | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/lib/libutil/humanize_number.3 b/lib/libutil/humanize_number.3 new file mode 100644 index 0000000..edcc7c0 --- /dev/null +++ b/lib/libutil/humanize_number.3 @@ -0,0 +1,137 @@ +.\" $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1999, 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn and by Tomas Svensson. +.\" +.\" 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 25, 2004 +.Dt HUMANIZE_NUMBER 3 +.Os +.Sh NAME +.Nm humanize_number +.Nd format a number into a human readable form +.Sh SYNOPSIS +.In util.h +.Ft int +.Fn humanize_number "char *buf" "size_t len" "int64_t number" "const char *suffix" "int scale" "int flags" +.Sh DESCRIPTION +The +.Fn humanize_number +function formats the signed 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 . +To use a specific prefix, specify this as +.Fa scale +(Multiplier = 1024 ^ scale). +This can not be combined with any of the +.Fa scale +flags below. +.Pp +The following flags may be passed in +.Pa scale : +.Bl -tag -width Dv -offset indent +.It Dv HN_AUTOSCALE +Format the buffer using the lowest multiplier possible. +.It Dv HN_GETSCALE +Return the prefix index number (the number of times +.Fa number +must be divided to fit) instead of formatting it to the buffer. +.El +.Pp +The following flags may be passed in +.Pa flags : +.Bl -tag -width Dv -offset indent +.It Dv HN_DECIMAL +If the final result is less than 10, display it using one digit. +.It Dv HN_NOSPACE +Do not put a space between +.Fa number +and the prefix. +.It Dv HN_B +Use 'B' (bytes) as prefix if the original result does not have a prefix. +.It Dv HN_DIVISOR_1000 +Divide +.Fa number +with 1000 instead of 1024. +.El +.Sh RETURN VALUES +.Fn humanize_number +returns the number of characters stored in +.Fa buffer +(excluding the terminating NUL) upon success, or \-1 upon failure. +If +.Dv HN_GETSCALE +is specified, the prefix index number will be returned instead. +.Sh SEE ALSO +.Xr humanize_number 9 +.Sh HISTORY +.Fn humanize_number +first appeared in +.Nx 2.0 . |