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 10.1