git.saurik.com Git - apple/libutil.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $
	2	.\" $FreeBSD: src/lib/libutil/humanize_number.3,v 1.8 2005/04/10 12:15:25 delphij Exp $
	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	.Pp
	80	The prefixes are:
	81	.Bl -column "Prefix" "Description" "Multiplier" -offset indent
	82	.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier"
	83	.It Li k Ta No kilo Ta 1024
	84	.It Li M Ta No mega Ta 1048576
	85	.It Li G Ta No giga Ta 1073741824
	86	.It Li T Ta No tera Ta 1099511627776
	87	.It Li P Ta No peta Ta 1125899906842624
	88	.It Li E Ta No exa Ta 1152921504606846976
	89	.El
	90	.Pp
	91	The
	92	.Fa len
	93	argument must be at least 4 plus the length of
	94	.Fa suffix ,
	95	in order to ensure a useful result is generated into
	96	.Fa buffer .
	97	To use a specific prefix, specify this as
	98	.Fa scale
	99	(multiplier = 1024 ^ scale).
	100	This cannot be combined with any of the
	101	.Fa scale
	102	flags below.
	103	.Pp
	104	The following flags may be passed in
	105	.Fa scale :
	106	.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
	107	.It Dv HN_AUTOSCALE
	108	Format the buffer using the lowest multiplier possible.
	109	.It Dv HN_GETSCALE
	110	Return the prefix index number (the number of times
	111	.Fa number
	112	must be divided to fit) instead of formatting it to the buffer.
	113	.El
	114	.Pp
	115	The following flags may be passed in
	116	.Fa flags :
	117	.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent
	118	.It Dv HN_DECIMAL
	119	If the final result is less than 10, display it using one digit.
	120	.It Dv HN_NOSPACE
	121	Do not put a space between
	122	.Fa number
	123	and the prefix.
	124	.It Dv HN_B
	125	Use
	126	.Ql B
	127	(bytes) as prefix if the original result does not have a prefix.
	128	.It Dv HN_DIVISOR_1000
	129	Divide
	130	.Fa number
	131	with 1000 instead of 1024.
	132	.El
	133	.Sh RETURN VALUES
	134	The
	135	.Fn humanize_number
	136	function returns the number of characters stored in
	137	.Fa buffer
	138	(excluding the terminating
	139	.Dv NUL )
	140	upon success, or \-1 upon failure.
	141	If
	142	.Dv HN_GETSCALE
	143	is specified, the prefix index number will be returned instead.
	144	.Sh HISTORY
	145	The
	146	.Fn humanize_number
	147	function first appeared in
	148	.Nx 2.0 .