humanize_number (3)

Leading comments

	$NetBSD: humanize_number.3,v 1.8 2008/04/30 13:10:50 martin Exp $

 Copyright (c) 1999, 2002, 2008 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 li...

(The comments found at the beginning of the groff file "man3/humanize_number.3bsd".)

NAME

dehumanize_number humanize_number - format a number into a human readable form and viceversa

LIBRARY

Lb libbsd

SYNOPSIS

In stdlib.h (See libbsd(7) for include usage.) Ft int Fn dehumanize_number const char *str int64_t *result Ft int Fn humanize_number char *buf size_t len int64_t number const char *suffix int scale int flags

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 long.

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.

The prefixes are:

Prefix Ta Description Ta Multiplier

k       kilo    1024

M mega    1048576

G      giga1073741824

Ttera1099511627776

Ppeta1125899906842624

Eexa1152921504606846976

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.

The following flags may be passed in scale

HN_AUTOSCALE

Format the buffer using the lowest multiplier possible.

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.

The following flags may be passed in flags

HN_DECIMAL

If the final result is less than 10, display it using one digit.

HN_NOSPACE

Do not put a space between Fa number and the prefix.

HN_B

Use 'B' (bytes) as prefix if the original result does not have a prefix.

HN_DIVISOR_1000

Divide Fa number with 1000 instead of 1024.

The Fn dehumanize_number function parses the string representing an integral value given in Fa str and stores the numerical value in the integer pointed to by Fa result . The provided string may hold one of the suffixes, which will be interpreted and used to scale up its accompanying numerical value.

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 HN_GETSCALE is specified, the prefix index number will be returned instead.

Fn dehumanize_number returns 0 if the string was parsed correctly. A -1 is returned to indicate failure and an error code is stored in errno

ERRORS

Fn dehumanize_number will fail and no number will be stored in Fa result if:

Bq Er EINVAL

The string in Fa str was empty or carried an unknown suffix.

Bq Er ERANGE

The string in Fa str represented a number that does not fit in Fa result .

SEE ALSO

humanize_number9

HISTORY

Fn humanize_number first appeared in Nx 2.0 .

Fn dehumanize_number first appeared in Nx 5.0 .