STRTOUL(3) | Library Functions Manual | STRTOUL(3)

# NAME

`strtoul`, `strtoull`, `strtoumax`, `strtouq` — convert a string to an unsigned long, unsigned long long or uintmax_t integer

# SYNOPSIS

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

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

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

`#include <inttypes.h>`

uintmax_t
`strtoumax`(const char *nptr, char **endptr, int base);

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

u_quad_t
`strtouq`(const char *nptr, char **endptr, int base);

# DESCRIPTION

The `strtoul`() function converts the string in nptr to an unsigned long value. The `strtoull`() function converts the string in nptr to an unsigned long long value. The `strtoumax`() function converts the string in nptr to a umaxint_t value. The `strtouq`() function is a deprecated equivalent of `strtoull`() 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. If the string in nptr represents a negative number, it will be converted to its unsigned equivalent. This behavior is consistent with what happens when a signed integer type is cast to its unsigned counterpart.

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 an unsigned long, unsigned long long, or uintmax_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, `strtoul`() stores the address of the first invalid character in *endptr. If there were no digits at all, however, `strtoul`() 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 `strtoul`(), `strtoull`(), `strtoumax`() and `strtouq`() functions return either the result of the conversion or, if there was a leading minus sign, the negation of the result of the conversion, unless the original (non-negated) value would overflow. If overflow occurs, `strtoul`() returns `ULONG_MAX`, `strtoull`() returns `ULLONG_MAX`, `strtoumax`() returns `UINTMAX_MAX`, `strtouq`() returns `ULLONG_MAX` and the global variable errno is set to `ERANGE`.

There is no way to determine if `strtoul`() has processed a negative number (and returned an unsigned value) short of examining the string in nptr directly.

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 `strtoul`(), and the return value of `strtoul`() cannot be used unambiguously to signal an error:

    char *ep;
    unsigned long ulval;

    ...

    errno = 0;
    ulval = strtoul(buf, &ep, 10);
    if (buf[0] == '\0' || *ep != '\0')
    	goto not_a_number;
    if (errno == ERANGE && ulval == ULONG_MAX)
    	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).

# 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

sscanf(3), strtol(3)

# STANDARDS

The `strtoul`(), `strtoull`(), and `strtoumax`() 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 `strtouq`() function is a BSD extension and is provided for backwards compatibility with legacy programs.

# BUGS

Ignores the current locale.

November 30, 2014 | Debian