| humanize_number.3 (135792) | humanize_number.3 (135820) |
|---|---|
| 1.\" $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $ | 1.\" $NetBSD: humanize_number.3,v 1.4 2003/04/16 13:34:37 wiz Exp $ |
| 2.\" $FreeBSD: head/lib/libutil/humanize_number.3 135792 2004-09-25 14:11:34Z pjd $ | 2.\" $FreeBSD: head/lib/libutil/humanize_number.3 135820 2004-09-26 12:08:31Z pjd $ |
| 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 --- 19 unchanged lines hidden (view full) --- 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.\" | 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 --- 19 unchanged lines hidden (view full) --- 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 Sep 25, 2004 | 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 54The 55.Fn humanize_number | 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 54The 55.Fn humanize_number |
| 56function formats the signed 64 bit quantity given in | 56function formats the signed 64-bit quantity given in |
| 57.Fa number 58into 59.Fa buffer . 60A space and then 61.Fa suffix 62is appended to the end. | 57.Fa number 58into 59.Fa buffer . 60A space and then 61.Fa suffix 62is appended to the end. |
| 63The buffer pointed to by |
|
| 63.Fa buffer 64must be at least 65.Fa len 66bytes bytes long. 67.Pp 68If the formatted number (including 69.Fa suffix ) 70would be too long to fit into 71.Fa buffer , 72then divide 73.Fa number 74by 1024 until it will. 75In this case, prefix 76.Fa suffix 77with the appropriate SI designator. 78.Pp 79The prefixes are: 80.Bl -column "Prefix" "Description" "Multiplier" -offset indent 81.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" | 64.Fa buffer 65must be at least 66.Fa len 67bytes bytes long. 68.Pp 69If the formatted number (including 70.Fa suffix ) 71would be too long to fit into 72.Fa buffer , 73then divide 74.Fa number 75by 1024 until it will. 76In this case, prefix 77.Fa suffix 78with the appropriate SI designator. 79.Pp 80The prefixes are: 81.Bl -column "Prefix" "Description" "Multiplier" -offset indent 82.It Sy "Prefix" Ta Sy "Description" Ta Sy "Multiplier" |
| 82.It k kilo 1024 83.It M mega 1048576 84.It G giga 1073741824 85.It T tera 1099511627776 86.It P peta 1125899906842624 87.It E exa 1152921504606846976 | 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 |
| 88.El 89.Pp | 89.El 90.Pp |
| 91The |
|
| 90.Fa len | 92.Fa len |
| 91must be at least 4 plus the length of | 93argument must be at least 4 plus the length of |
| 92.Fa suffix , 93in order to ensure a useful result is generated into 94.Fa buffer . 95To use a specific prefix, specify this as 96.Fa scale | 94.Fa suffix , 95in order to ensure a useful result is generated into 96.Fa buffer . 97To use a specific prefix, specify this as 98.Fa scale |
| 97(Multiplier = 1024 ^ scale). 98This can not be combined with any of the | 99(multiplier = 1024 ^ scale). 100This cannot be combined with any of the |
| 99.Fa scale 100flags below. 101.Pp 102The following flags may be passed in | 101.Fa scale 102flags below. 103.Pp 104The following flags may be passed in |
| 103.Pa scale : 104.Bl -tag -width Dv -offset indent | 105.Fa scale : 106.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent |
| 105.It Dv HN_AUTOSCALE 106Format the buffer using the lowest multiplier possible. 107.It Dv HN_GETSCALE 108Return the prefix index number (the number of times 109.Fa number 110must be divided to fit) instead of formatting it to the buffer. 111.El 112.Pp 113The following flags may be passed in | 107.It Dv HN_AUTOSCALE 108Format the buffer using the lowest multiplier possible. 109.It Dv HN_GETSCALE 110Return the prefix index number (the number of times 111.Fa number 112must be divided to fit) instead of formatting it to the buffer. 113.El 114.Pp 115The following flags may be passed in |
| 114.Pa flags : 115.Bl -tag -width Dv -offset indent | 116.Fa flags : 117.Bl -tag -width ".Dv HN_DIVISOR_1000" -offset indent |
| 116.It Dv HN_DECIMAL 117If the final result is less than 10, display it using one digit. 118.It Dv HN_NOSPACE 119Do not put a space between 120.Fa number 121and the prefix. 122.It Dv HN_B | 118.It Dv HN_DECIMAL 119If the final result is less than 10, display it using one digit. 120.It Dv HN_NOSPACE 121Do not put a space between 122.Fa number 123and the prefix. 124.It Dv HN_B |
| 123Use 'B' (bytes) as prefix if the original result does not have a prefix. | 125Use 126.Ql B 127(bytes) as prefix if the original result does not have a prefix. |
| 124.It Dv HN_DIVISOR_1000 125Divide 126.Fa number 127with 1000 instead of 1024. 128.El 129.Sh RETURN VALUES | 128.It Dv HN_DIVISOR_1000 129Divide 130.Fa number 131with 1000 instead of 1024. 132.El 133.Sh RETURN VALUES |
| 134The |
|
| 130.Fn humanize_number | 135.Fn humanize_number |
| 131returns the number of characters stored in | 136function returns the number of characters stored in |
| 132.Fa buffer | 137.Fa buffer |
| 133(excluding the terminating NUL) upon success, or \-1 upon failure. | 138(excluding the terminating 139.Dv NUL ) 140upon success, or \-1 upon failure. |
| 134If 135.Dv HN_GETSCALE 136is specified, the prefix index number will be returned instead. 137.Sh HISTORY | 141If 142.Dv HN_GETSCALE 143is specified, the prefix index number will be returned instead. 144.Sh HISTORY |
| 145The |
|
| 138.Fn humanize_number | 146.Fn humanize_number |
| 139first appeared in | 147function first appeared in |
| 140.Nx 2.0 . | 148.Nx 2.0 . |