C Reference ยท stdlib.h
C strtol() and strtoul() functions
Reference for C strtol(), strtoll(), strtoul() and strtoull(): convert strings to integers in any base, detect errors with endptr and errno, avoid pitfalls.
strtol() converts the beginning of a string to a long. Unlike atoi(), it tells you where the number ended, reports overflow through errno, and understands bases from 2 to 36. That makes it the standard tool for turning text into integers when the text comes from a user, a file or the network.
The family has four members: strtol (long), strtoll (long long), strtoul (unsigned long) and strtoull (unsigned long long). They all work the same way, so this page uses strtol for the explanations.
#include <stdlib.h> long strtol(const char *restrict nptr, char **restrict endptr, int base);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
long strtol (const char *restrict nptr, char **restrict endptr, int base); long long strtoll (const char *restrict nptr, char **restrict endptr, int base); unsigned long strtoul (const char *restrict nptr, char **restrict endptr, int base); unsigned long long strtoull(const char *restrict nptr, char **restrict endptr, int base);
| Name | Description |
|---|---|
nptr |
The string to convert. Leading white space is skipped, then an optional + or -, then digits. |
endptr |
If not NULL, receives a pointer to the first character that was not converted. |
base |
2 to 36, or 0 to detect the base from the prefix (0x/0X hex, 0 octal, otherwise decimal). With base 16 a leading 0x is allowed and skipped. |
Returns: the converted value. If no conversion could be made, it returns 0 and sets *endptr to nptr. If the value does not fit, it returns LONG_MAX, LONG_MIN (or ULONG_MAX) and sets errno to ERANGE.
Errors / undefined behavior: an invalid base (neither 0 nor 2 to 36) is not a valid argument; implementations may set errno to EINVAL. nptr must point to a valid string.
Usage notes
- A complete check has three parts: set
errno = 0first (the functions never clear it), compareend == textto catch "no digits", and testerrno == ERANGE. To demand that the whole string is a number, also check*end == '\0'; allowing trailing white space needs an extra loop. - A result of 0 is ambiguous without the
endptrcheck:"0"and"abc"both return 0. strtoulaccepts a minus sign.strtoul("-1", ...)returnsULONG_MAX(the negated value converted to unsigned) without settingerrno. Reject a leading-yourself when negative input is invalid.longis 32 bits on 64-bit Windows and 64 bits on 64-bit Linux. When you need a fixed range, usestrtolland compare againstINT_MIN/INT_MAXbefore narrowing toint.- Binary prefixes: C23 lets base 0 and base 2 accept a
0bprefix, but the C library on our runner (glibc 2.28) predates that and stops after the0. Strip0byourself for portable code. - Complexity: linear in the number of characters consumed.
- Floating point has its own function,
strtod().