strtoull() — Convert string to unsigned long long

Standards

Standards / Extensions	C or C++	Dependencies
Language Environment® C99 Single UNIX Specification, Version 3 C++ TR1 C99	both	OS/390® V2R9

Format

#include <stdlib.h>

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

Compile requirement: Use of this function requires the long long data type. See z/OS XL C/C++ Language Reference for information on how to make long long available.

General description

Converts nptr, a character string, to an unsigned long long value.

The function decomposes the entire string into three parts:

A sequence of characters, which in the current locale are defined as white space characters. This part may be empty.
A sequence of characters interpreted as an unsigned integer in some base notation. This is the subject sequence.
A sequence of unrecognized characters.

The base notation is determined by base, if base is greater than zero. If base is zero, the base notation is determined by the format of the sequence of characters that follow an optional plus or optional minus sign.

10: Sequence starts with nonzero decimal digit.
8: Sequence starts with 0, followed by a sequence of digits with values from 0 to 7.
16: Sequence starts with either 0x or 0X, followed by digits, and letters A through F or a through f.

If the base is greater than zero, the subject sequence contains decimal digits and letters, possibly preceded by either a plus or a minus sign. The letters a (or A) through z (or Z) represent values from 10 through 36, but only those letters whose value is less than the value of the base are allowed. The function stops reading the string at the first character that it cannot recognize as part of a number. This character can be the first numeric character greater than or equal to the base. The strtoull() function sets endptr to point to the end of the resulting output string if a conversion is performed and provided that endptr is not a NULL pointer.

When you are using the strtoull() function, nptr should point to a string with the following form:

If base is in the range of 2-36, it becomes the base of the number. If base is 0, the prefix determines the base (8, 16 or 10): the prefix 0 means base 8; the prefix 0x or 0X means base 16; using any other digit without a prefix means decimal.

The pointer to the converted characters, even if conversion was unsuccessful, is stored in the object pointed to by endptr, as long as endptr is not a NULL pointer.

Returned value

If successful, strtoull() returns the converted unsigned long long value, represented in the string.

If unsuccessful, strtoull() returns 0 if no conversion could be performed. If the correct value is outside the range of representable values, strtoull() returns ULLONG_MAX (ULONGLONG_MAX). If the value of base is not supported, strtoull() returns 0.

If unsuccessful strtoull() sets errno to one of the following values:

Error Code: Description
EINVAL: The value of base is not supported.
ERANGE: The conversion caused an overflow.