Skip to content
Tutorials Center
My learning

Topics

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.

C
#include <stdlib.h>

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

Try it

C Checking the whole string

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.

C Bases and unsigned conversion

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

C
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 = 0 first (the functions never clear it), compare end == text to catch "no digits", and test errno == 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 endptr check: "0" and "abc" both return 0.
  • strtoul accepts a minus sign. strtoul("-1", ...) returns ULONG_MAX (the negated value converted to unsigned) without setting errno. Reject a leading - yourself when negative input is invalid.
  • long is 32 bits on 64-bit Windows and 64 bits on 64-bit Linux. When you need a fixed range, use strtoll and compare against INT_MIN/INT_MAX before narrowing to int.
  • Binary prefixes: C23 lets base 0 and base 2 accept a 0b prefix, but the C library on our runner (glibc 2.28) predates that and stops after the 0. Strip 0b yourself for portable code.
  • Complexity: linear in the number of characters consumed.
  • Floating point has its own function, strtod().