STRTOL(3) | Library Functions Manual | STRTOL(3) |
long int
strtol(const char * restrict nptr, char ** restrict endptr, int base);
long long int
strtoll(const char * restrict nptr, char ** restrict endptr, int base);
#include <inttypes.h>
intmax_t
strtoimax(const char * restrict nptr, char ** restrict endptr, int base);
#include <sys/types.h>
#include <stdlib.h>
#include <limits.h>
quad_t
strtoq(const char * restrict nptr, char ** restrict endptr, int base);
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 appropriate value in the obvious manner, stopping at the first character which is not 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 non-nil, the functions store the address of the first invalid character in *endptr. If there were no digits at all, however, the functions store the original value of nptr in *endptr. (Thus, if *nptr is not ‘\0
’ but **endptr is ‘\0
’ on return, the entire string was valid.)
If no error occurs, errno is left unchanged. This behavior (which is unlike most library functions) is guaranteed by the pertinent standards.
char *ep; long lval; ... errno = 0; lval = strtol(buf, &ep, 10); if (ep == buf) goto not_a_number; if (*ep != '\0') goto trailing_garbage; if (errno) { assert(errno == ERANGE); assert(lval == LONG_MAX || lval == LONG_MIN); goto out_of_range; }
This example will accept “12” but not “12foo” or “12\n”. If trailing whitespace is acceptable, further checks must be done on *ep; alternately, use sscanf(3).
If strtol() is being used instead of atoi(3), error checking is further complicated because the desired return value is an int
rather than a long
; however, on some architectures integers and long integers are the same size. Thus the following is necessary:
char *ep; int ival; long lval; ... errno = 0; lval = strtol(buf, &ep, 10); if (ep == buf) goto not_a_number; if (*ep != '\0') goto trailing_garbage; if (errno == ERANGE || lval < INT_MIN || INT_MAX < lval) goto out_of_range; assert(errno == 0); assert(INT_MIN <= lval); assert(lval <= INT_MAX); ival = lval;
The strtoq() function is a BSD legacy function equivalent to strtoll() and should not be used in a new code.
April 30, 2015 | NetBSD 7.2 |