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

# NAME

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

# SYNOPSIS

`#include <limits.h>`
`#include <stdlib.h>`

long
`strtol`(const char *nptr, char **endptr, int base);

long long
`strtoll`(const char *nptr, char **endptr, int base);

`#include <inttypes.h>`

intmax_t
`strtoimax`(const char *nptr, char **endptr, int base);

`#include <sys/types.h>`
`#include <limits.h>`
`#include <stdlib.h>`

quad_t
`strtoq`(const char *nptr, char **endptr, int base);

# DESCRIPTION

The `strtol`() function converts the string in nptr to a long value. The `strtoll`() function converts the string in nptr to a long long value. The `strtoimax`() function converts the string in nptr to an intmax_t value. The `strtoq`() function is a deprecated equivalent of `strtoll`() and is provided for backwards compatibility with legacy programs. The conversion is done according to the given base, which must be a number between 2 and 36 inclusive or the special value 0.

The string may begin with an arbitrary amount of whitespace (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 a long, long long, or intmax_t 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-null, `strtol`() stores the address of the first invalid character in *endptr. If there were no digits at all, however, `strtol`() stores 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`(), `strtoll`(), `strtoimax`(), and `strtoq`() functions return the result of the conversion. If overflow or underflow occurs, errno is set to `ERANGE` and the function return value is as follows:

Function | underflow | overflow
`strtol`() | `LONG_MIN` | `LONG_MAX`
`strtoll`() | `LLONG_MIN` | `LLONG_MAX`
`strtoimax`() | `INTMAX_MIN` | `INTMAX_MAX`
`strtoq`() | `LLONG_MIN` | `LLONG_MAX`

If there is no valid digit, 0 is returned. If base is invalid, 0 is returned and the global variable errno is set to `EINVAL`.

# EXAMPLES

Ensuring that a string is a valid number (i.e., in range and containing no trailing characters) requires clearing errno beforehand explicitly since errno is not changed on a successful call to `strtol`(), and the return value of `strtol`() cannot be used unambiguously to signal an error:

    char *ep;
    long lval;

    ...

    errno = 0;
    lval = strtol(buf, &ep, 10);
    if (buf[0] == '\0' || *ep != '\0')
    	goto not_a_number;
    if (errno == ERANGE && (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 (buf[0] == '\0' || *ep != '\0')
         goto not_a_number;
    if ((errno == ERANGE && (lval == LONG_MAX || lval == LONG_MIN)) ||
        (lval > INT_MAX || lval < INT_MIN))
         goto out_of_range;
    ival = lval;

# ERRORS

[`EINVAL`]
  The value of base was neither between 2 and 36 inclusive nor 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), sscanf(3), strtod(3), strtonum(3), strtoul(3)

# STANDARDS

The `strtol`(), `strtoll`(), and `strtoimax`() functions conform to ISO/IEC 9899:1999 (“ISO C99”). Setting errno to `EINVAL` is an extension to that standard required by IEEE Std 1003.1-2008 (“POSIX.1”).

The `strtoq`() function is a BSD extension and is provided for backwards compatibility with legacy programs.

# BUGS

Ignores the current locale.

April 14, 2015 | Debian