---
name: "strtol"
section: "3"
platform: "macos"
package: "Libc"
version: "1752.120.2"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/strtol"
---

# strtol(3)

convert a string value to a long, long long, intmax\_t or quad\_t integer

## NAME

**strtoimax**, **strtol**, **strtoll**, **strtoq** – convert a string value to a *long*, *long long*, *intmax\_t* or *quad\_t* integer

## LIBRARY

Standard C Library (libc, -lc)

## SYNOPSIS

**#include \<inttypes.h\>**

*intmax\_t*\

**strtoimax**(*const char \*restrict str*, *char \*\*restrict endptr*, *int base*);

**#include \<stdlib.h\>**

*long*\

**strtol**(*const char \*restrict str*, *char \*\*restrict endptr*, *int base*);

*long* *long*\

**strtoll**(*const char \*restrict str*, *char \*\*restrict endptr*, *int base*);

**#include \<sys/types.h\>**

**#include \<stdlib.h\>**

**#include \<limits.h\>**

*quad\_t*\

**strtoq**(*const char \*str*, *char \*\*endptr*, *int base*);

## DESCRIPTION

The **strtol**() function converts the string in *str* to a *long* value. The **strtoll**() function converts the string in *str* to a *long long* value. The **strtoimax**() function converts the string in *str* to an *intmax\_t* value. The **strtoq**() function converts the string in *str* 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)](/isspace/3.md)) 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*, *intmax\_t* or *quad\_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 not 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 *str* in *\*endptr*. (Thus, if *\*str* is not ‘\\0’ but *\*\*endptr* is ‘\\0’ on return, the entire string was valid.)

Extended locale versions of these functions are documented in [strtol\_l(3)](/strtol_l/3.md). See [xlocale(3)](/xlocale/3.md) for more information.

## RETURN VALUES

The **strtol**(), **strtoll**(), **strtoimax**(), and **strtoq**() functions return the result of the conversion, unless the value would underflow or overflow. If no conversion could be performed, 0 is returned and the global variable *errno* is set to EINVAL (the last feature is not portable across all platforms). If an overflow or underflow occurs, *errno* is set to ERANGE and the function return value is clamped according to the following table.

| | | |
| --- | --- | --- |
| **Function** | **underflow** | **overflow** |
| **strtol**() | LONG\_MIN | LONG\_MAX |
| **strtoll**() | LLONG\_MIN | LLONG\_MAX |
| **strtoimax**() | INTMAX\_MIN | INTMAX\_MAX |
| **strtoq**() | LLONG\_MIN | LLONG\_MAX |

## ERRORS

- \[EINVAL\]

  The value of *base* is not supported or no conversion could be performed (the last feature is not portable across all platforms).

- \[ERANGE\]

  The given string was out of range; the value converted has been clamped.

## LEGACY SYNOPSIS

**#include \<stdlib.h\>** **#include \<limits.h\>**

⟨limits.h⟩ is necessary for the **strtol**() and **strtoll**() functions.

## SEE ALSO

[atof(3)](/atof/3.md), [atoi(3)](/atoi/3.md), [atol(3)](/atol/3.md), [strtod(3)](/strtod/3.md), [strtol\_l(3)](/strtol_l/3.md), [strtoul(3)](/strtoul/3.md), [wcstol(3)](/wcstol/3.md), [compat(5)](/compat/5.md)

## STANDARDS

The **strtol**() function conforms to ISO/IEC 9899:1990 (“ISO C90”). The **strtoll**() and **strtoimax**() functions conform to ISO/IEC 9899:1999 (“ISO C99”). The BSD **strtoq**() function is deprecated.