expand_number3
Parse a number from human readable form
Usage
#include <libutil.h>
int
expand_number(const char *buf, int64_t *num);
int
expand_unsigned(const char *buf, uint64_t *num);
Library
System Utilities Library (libutil, -lutil)
Overview
The expand_number() function parses the number in the string pointed to by its buf argument and stores the number it represents as a signed 64-bit quantity in the location pointed to by its *num argument.
The expand_unsigned() function is similar to expand_number(), but accepts only positive numbers in the range [0,UINT64_MAX].
Both functions interpret the input “-0” as 0.
The input string must consist of a decimal number, optionally preceded by a ‘+’ or ‘-’ sign, and optionally followed, without intervening whitespace, by a suffix indicating a power-of-two multiplier to apply. Any amount of whitespace at the beginning of the string will be ignored.
Recognized suffixes are:
| Suffix | Description | Multiplier |
| K | kilo | 1,024 |
| M | mega | 1,048,576 |
| G | giga | 1,073,741,824 |
| T | tera | 1,099,511,627,776 |
| P | peta | 1,125,899,906,842,624 |
| E | exa | 1,152,921,504,606,846,976 |
For historical reasons, the expand_number() function accepts and ignores a single “B” suffix at the end of the buf string (i.e. “5b” is interpreted as 5, and “5kb” is interpreted as 5,120). However, the usage of this suffix is discouraged.
For backward compatibility reasons, if the compiler supports generic selection, a macro is provided which automatically replaces calls to expand_number() with calls to expand_unsigned() if the type of the actual num argument is compatible with uint64_t *.
Return values
The expand_number() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.
Errors
The expand_number() and expand_unsigned() functions will fail if:
- [EINVAL]
-
The given string does not contain a valid number.
- [EINVAL]
-
An unrecognized suffix was encountered.
- [ERANGE]
-
The given string represents a number which does not fit into an int64_t (for
expand_number()) or uint64_t (forexpand_unsigned()).
Releases
46 releases since FreeBSD 6.3-RELEASE; the text changed 34 times.