>>-+------------+--+------+--+----+--digits-------------------->< '-whitespace-' +- + -+ +-0--+ '- – --' +-0x-+ '-0X-'
Format (strtoul())
#include <stdlib.h>
unsigned long int strtoul(const char *nptr, char **endptr, int base);Format (strtoull())
#include <stdlib.h>
unsigned long long int strtoull(char *string, char **endptr, int base);Language Level: ANSI
Threadsafe: Yes.
Locale Sensitive: The behavior of these functions might be affected by the LC_CTYPE category of the current locale. For more information, see Understanding CCSIDs and Locales.
Description
The strtoul() function converts a character string to an unsigned long integer value. The parameter nptr points to a sequence of characters that can be interpreted as a numeric value of type unsigned long int.
The strtoull() function converts a character string to an unsigned long long integer value. The parameter nptr points to a sequence of characters that can be interpreted as a numeric value of type unsigned long long int.
When you use these functions, the nptr parameter should point to a string with the following form:
If the base parameter is a value between 2 and 36, the subject sequence's expected form is a sequence of letters and digits representing an integer whose radix is specified by the base parameter. This sequence is optionally preceded by a positive (+) or negative (-) sign. Letters from a to z inclusive (either upper or lower case) are ascribed the values 10 to 35. Only letters whose ascribed values are less than that of the base parameter are permitted. If the base parameter has a value of 16 the characters 0x or 0X optionally precede the sequence of letters and digits, following the positive (+) or negative (-) sign, if present.
If the value of the base parameter is 0, the string determines the base. After an optional leading sign a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and all other leading characters result in decimal conversion.
These functions scan the string up to the first character that is inconsistent with the base parameter. This character may be the null character ('\0') at the end of the string. Leading white-space characters are ignored, and an optional sign may precede the digits.
If the value of the endptr parameter is not null a pointer, a pointer to the character that ended the scan is stored in the value pointed to by endptr. If a value cannot be formed, the value pointed to by endptr is set to the nptr parameter.
Return Value
If base has an invalid value (less than 0, 1, or greater than 36), errno is set to EINVAL and 0 is returned. The value pointed to by the endptr parameter is set to the value of the nptr parameter.
If the value is outside the range of representable values, errno is set to ERANGE. The strtoul() function will return ULONG_MAX and the strtoull() function will return ULONGLONG_MAX.
If no characters are converted, the strtoull() function will set errno to EINVAL and 0 is returned. The strtoul() function will return 0 but will not set errno to EINVAL. In both cases the value pointed to by endptr is set to the value of the nptr parameter. Upon successful completion, both functions return the converted value.
Example that uses strtoul()
This example converts the string to an unsigned long value. It prints out the converted value and the substring that stopped the conversion.
#include <stdio.h>
#include <stdlib.h>
#define BASE 2
int main(void)
{
char *string, *stopstring;
unsigned long ul;
string = "1000e13 e";
printf("string = %s\n", string);
ul = strtoul(string, &stopstring, BASE);
printf(" strtoul = %ld (base %d)\n", ul, BASE);
printf(" Stopped scan at %s\n\n", stopstring);
}
/***************** Output should be similar to: *****************
string = 1000e13 e
strtoul = 8 (base 2)
Stopped scan at e13 e
*/Related Information