Sorry I munged it on the first try. Resending to PSARC-EXT.
Eric Lowe wrote:
> Subject: PSARC-EXT FastTrack [10/17/2006]: Human-readable number library
> routine
>
> I am sponsoring the following fast-track for Yann Poupet
> <yann.poupet at free.fr>, an OpenSolaris contributor. The requested
> release binding is minor. The commitment level of the interface
> is Committed (formerly Stable). This case introduces a new header
> file, conversion.h, for future addition of related routines;
> the routine will be added to libc.
>
> ----
> Standard C Library Functions humanize_number(3C)
>
> NAME
> humanize_number - convert a number to a human-readable string
>
> SYNOPSIS
> #include <conversion.h>
>
> int humanize_number(int64_t value, const char *fmt, char *buffer,
> size_t buf_len)
>
> DESCRIPTION
> The humanize_number() function will convert the signed integer
> <value> to a string, which will write at most <buf_len> bytes
> to the output <buffer>. The format of the output string
> is described by the <fmt> string.
>
> Conversion Specification
> The <fmt> string determines how <value> will be formatted to
> the output in a fashion similar to sprintf(). Each conversion
> specifier within the string consists of the % character, after
> which the following appear in sequence:
>
> o One or more of the following modifiers:
> '0' : the resulting string is zero padded.
> '-' : the resulting string is left aligned.
> '+' : the resulting string's first char is a
> '+' if result is greater than zero.
> ' ' : the resulting string's first char is a
> space is the result is greater than zero;
> used only if the '+' modifier is not
> defined.
> '#' : suppress trailing zeroes.
> o An optional decimal length. If the result is smaller,
> the output will be padded according to the modifiers
> if present, otherwise the result will be space-padded.
> o An optional decimal precision, expressed as .# where
> # is an unsigned decimal integer. When not specified,
> three digits is the default precision.
> o An optional 'b' character, which will express the result
> as radix-2 rather than radix-10 (radix 2 uses 1024^N
> whereas the default of radix 10 uses 1000^N to convert
> the number).
> o An optional unit character, from the following set:
> 'A' : the unit is choosen automatically for the best
> human-readable result. The integer part of the
> result will be between 0 and 999 when radix-10
> is used for the conversion, or 0 to 1023 when
> radix-2 is used for the conversion.
> 'N' : use no metric unit for conversion.
> 'K' : use the metric unit of kilo.
> 'M' : use the metric unit of mega.
> 'G' : use the metric unit of giga.
> 'P' : use the metric unit of peta.
> 'T' : use the metric unit of tera.
> 'E' : use the metric unit of exa.
>
> RETURN VALUE
> The humanize_number() function returns the number of bytes
> written into <buffer> if less than or equal to <buf_len>,
> otherwise returns the number of bytes that would have been
> written to <buffer> if <buf_len> had been sufficiently large.
> The value of <buf_len> may be passed as zero, and/or <buffer>
> may be a null pointer; this will result in a return value of
> the minimal-length buffer required to contain a complete
> result (minus a terminating NUL character).
>
> EXAMPLES
> humanize_number(123456789, "%5M", buffer, len)
> will output "123.457M" into the buffer
>
> humanize_number(123456789, "%5.M", buffer, len)
> will output " 123M" into the buffer
>
> humanize_number(123456789, "%5.0M", buffer, len)
> will output " 123M" into the buffer
>
> humanize_number(123456789, "%5.1M", buffer, len)
> will output "123.5M" into the buffer
>
> humanize_number(123456789, "%5.2M", buffer, len)
> will output "123.46M" into the buffer
>
> humanize_number(123456789, "%5.3M", buffer, len)
> will output "123.457M" into the buffer
>
> humanize_number(123456789, "%5.4M", buffer, len)
> will output "123.4568M" into the buffer
>
> humanize_number(123456789, "%+5.2K", buffer, len)
> will output "+123456.79K" into the buffer
>
> humanize_number(123456789, "%N", buffer, len)
> will output "123456789" into the buffer.
>
> humanize_number(0,"%A",buffer,len)
> will output "0.000" into the buffer.
>
> humanize_number(0,"%b",buffer,len)
> will output "0.000" into the buffer.
>
> humanize_number(0,"%bK",buffer,len)
> will output "0.000K" into the buffer.
>
> humanize_number(1047552,"FOO %0#5.4bA BAR", buffer, len)
> will output "FOO 01023K BAR" into the buffer.
>
> ATTRIBUTES
> Interface Stability Standard
> MT-Level Thread and async-signal safe
>
> 6. Resources and Schedule
> 6.4. Steering Committee requested information
> 6.4.1. Consolidation C-team Name:
> OS/Net
> 6.5. ARC review type: FastTrack
