STRTOL(3)

STRTOL(3) | Library Functions Manual | STRTOL(3)

# NAME

strtol, strtoll, strtoimax, strtoq — convert string value to a long, long long, intmax_t or quad_t integer

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

#include <stdlib.h>
#include <limits.h>
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);

# DESCRIPTION

The strtol() function converts the string in nptr to a long int value. The strtoll() function converts the string in nptr to a long long int value. The strtoimax() function converts the string in nptr to an intmax_t value. The strtoq() function converts the string in nptr to a 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`’ or ‘`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.)

# RETURN VALUES

The strtol() function returns the result of the conversion, unless the value would underflow or overflow. If an underflow occurs, strtol() returns `LONG_MIN`, strtoll() returns `LLONG_MIN`, and strtoimax() returns `INTMAX_MIN`. If an overflow occurs, strtol() returns `LONG_MAX`, strtoll() returns `LLONG_MAX`, and strtoimax() returns `INTMAX_MAX`. In these cases, errno is set to `ERANGE`. If the base argument is not supported then errno is set to `EINVAL` and the functions return 0.
If no error occurs, errno is left unchanged. This behavior (which is unlike most library functions) is guaranteed by the pertinent standards.

# EXAMPLES

Because the return value of strtol() cannot be used unambiguously to detect an error, errno is left unchanged after a successful call. To ensure that a string is a valid number (i.e., in range and containing no trailing characters), clear errno beforehand explicitly, then check it afterwards:

    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;

# ERRORS

[`EINVAL`]
  The base is not between 2 and 36 and does not contain the special value 0.
[`ERANGE`]
  The given string was out of range; the value converted has been clamped.

# SEE ALSO

atof(3), atoi(3), atol(3), atoll(3), strtod(3), strtou(3), strtoul(3), strtoull(3), strtoumax(3)

# STANDARDS

The strtol() function conforms to ANSI X3.159-1989 (“ANSI C89”). The strtoll() and strtoimax() functions conform to ISO/IEC 9899:1999 (“ISO C99”).
The strtoq() function is a BSD legacy function equivalent to strtoll() and should not be used in a new code.

# BUGS

Ignores the current locale.

November 4, 2016 | NetBSD 8.0