strtonum(3) [mojave man page]
STRTONUM(3) BSD Library Functions Manual STRTONUM(3) NAME
strtonum -- reliably convert string value to an integer LIBRARY
Utility functions from BSD systems (libbsd, -lbsd) SYNOPSIS
#include <limits.h> #include <bsd/stdlib.h> long long strtonum(const char *nptr, long long minval, long long maxval, const char **errstr); DESCRIPTION
The strtonum() function converts the string in nptr to a long long value. The strtonum() function was designed to facilitate safe, robust programming and overcome the shortcomings of the atoi(3) and strtol(3) family of interfaces. The string may begin with an arbitrary amount of whitespace (as determined by isspace(3)) followed by a single optional '+' or '-' sign. The remainder of the string is converted to a long long value according to base 10. The value obtained is then checked against the provided minval and maxval bounds. If errstr is non-null, strtonum() stores an error string in *errstr indicating the failure. RETURN VALUES
The strtonum() function returns the result of the conversion, unless the value would exceed the provided bounds or is invalid. On error, 0 is returned, errno is set, and errstr will point to an error message. On success, *errstr will be set to NULL; this fact can be used to dif- ferentiate a successful return of 0 from an error. EXAMPLES
Using strtonum() correctly is meant to be simpler than the alternative functions. int iterations; const char *errstr; iterations = strtonum(optarg, 1, 64, &errstr); if (errstr) errx(1, "number of iterations is %s: %s", errstr, optarg); The above example will guarantee that the value of iterations is between 1 and 64 (inclusive). ERRORS
[ERANGE] The given string was out of range. [EINVAL] The given string did not consist solely of digit characters. [EINVAL] The supplied minval was larger than maxval. If an error occurs, errstr will be set to one of the following strings: too large The result was larger than the provided maximum value. too small The result was smaller than the provided minimum value. invalid The string did not consist solely of digit characters. SEE ALSO
atof(3), atoi(3), atol(3), atoll(3), sscanf(3), strtod(3), strtol(3), strtoul(3) STANDARDS
The strtonum() function is a BSD extension. The existing alternatives, such as atoi(3) and strtol(3), are either impossible or difficult to use safely. HISTORY
The strtonum() function first appeared in OpenBSD 3.6. BSD April 29, 2004 BSD
Check Out this Related Man Page
STRTOUL(3) BSD Library Functions Manual STRTOUL(3) NAME
strtoul, strtoull, strtoumax, strtouq -- convert a string to an unsigned long, unsigned long long, uintmax_t, or u_quad_t integer LIBRARY
Standard C Library (libc, -lc) SYNOPSIS
#include <stdlib.h> #include <limits.h> unsigned long strtoul(const char * restrict nptr, char ** restrict endptr, int base); unsigned long long strtoull(const char * restrict nptr, char ** restrict endptr, int base); #include <inttypes.h> uintmax_t strtoumax(const char * restrict nptr, char ** restrict endptr, int base); #include <sys/types.h> #include <stdlib.h> #include <limits.h> u_quad_t strtouq(const char *nptr, char **endptr, int base); DESCRIPTION
The strtoul() function converts the string in nptr to an unsigned long value. The strtoull() function converts the string in nptr to an unsigned long long value. The strtoumax() function converts the string in nptr to an uintmax_t value. The strtouq() function converts the string in nptr to a u_quad_t value. The conversion is done according to the given base, which must be between 2 and 36 inclusive, or be the special value 0. The string may begin with an arbitrary amount of white space (as determined by isspace(3)) followed by a single optional '+' or '-' sign. If base is zero or 16, the string may then include a ``0x'' prefix, and the number will be read in base 16; otherwise, a zero base is taken as 10 (decimal) unless the next character is '0', in which case it is taken as 8 (octal). The remainder of the string is converted to an unsigned long value in the obvious manner, stopping at the end of the string or at the first character that does not produce a valid digit in the given base. (In bases above 10, the letter 'A' in either upper or lower case represents 10, 'B' represents 11, and so forth, with 'Z' representing 35.) If endptr is not NULL, strtoul() stores the address of the first invalid character in *endptr. If there were no digits at all, however, strtoul() stores the original value of nptr in *endptr. (Thus, if *nptr is not ' ' but **endptr is ' ' on return, the entire string was valid.) RETURN VALUES
The strtoul(), strtoull(), strtoumax() and strtouq() functions return either the result of the conversion or, if there was a leading minus sign, the negation of the result of the conversion, unless the original (non-negated) value would overflow; in the latter case, strtoul() returns ULONG_MAX, strtoull() returns ULLONG_MAX, strtoumax() returns UINTMAX_MAX, and strtouq() returns ULLONG_MAX. In all cases, errno is set to ERANGE. If no conversion could be performed, 0 is returned and the global variable errno is set to EINVAL (the last feature is not portable across all platforms). ERRORS
[EINVAL] The value of base is not supported or no conversion could be performed (the last feature is not portable across all plat- forms). [ERANGE] The given string was out of range; the value converted has been clamped. SEE ALSO
strtol(3), strtonum(3), wcstoul(3) STANDARDS
The strtoul() function conforms to ISO/IEC 9899:1990 (``ISO C90''). The strtoull() and strtoumax() functions conform to ISO/IEC 9899:1999 (``ISO C99''). The BSD strtouq() function is deprecated. BSD
November 28, 2001 BSD