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

`strtol`

, `strtoll`

,
`strtoimax`

, `strtoq`

—
convert string value to a long, long long or intmax_t
integer

```
#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`);

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.)

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`

.

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;

atof(3), atoi(3), atol(3), atoll(3), sscanf(3), strtod(3), strtonum(3), strtoul(3)

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.

Ignores the current locale.

April 14, 2015 | OpenBSD-6.0 |