The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> wcstoul, wcstoull - convert a wide-character string to an unsigned long

#### SYNOPSIS

> ``#include <wchar.h>
> unsigned long wcstoul(const wchar_t *restrict` nptr`,
> wchar_t **restrict` endptr`, int` base`);
> unsigned long long wcstoull(const wchar_t *restrict` nptr`,
> wchar_t **restrict` endptr`, int` base`);
> ``

#### DESCRIPTION

> [CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2008 defers to the ISO C standard.

> The wcstoul() and wcstoull() functions shall convert the initial portion of the wide-character string pointed to by nptr to unsigned long and unsigned long long representation, respectively. First, they shall decompose the input wide-character string into three parts:

> 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by iswspace())

> 2. A subject sequence interpreted as an integer represented in some radix determined by the value of base

> 3. A final wide-character string of one or more unrecognized wide-character codes, including the terminating null wide-character code of the input wide-character string

> Then they shall attempt to convert the subject sequence to an unsigned integer, and return the result.

> If base is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, or hexadecimal constant, any of which may be preceded by a `'+'` or `'-'` sign. A decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits. An octal constant consists of the prefix `'0'` optionally followed by a sequence of the digits `'0'` to `'7'` only. A hexadecimal constant consists of the prefix 0x or 0X followed by a sequence of the decimal digits and letters `'a'` (or `'A'` ) to `'f'` (or `'F'` ) with values 10 to 15 respectively.

> If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base, optionally preceded by a `'+'` or `'-'` sign, but not including an integer suffix. The letters from `'a'` (or `'A'` ) to `'z'` (or `'Z'` ) inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less than that of base shall be permitted. If the value of base is 16, the wide-character codes 0x or 0X may optionally precede the sequence of letters and digits, following the sign if present.

> The subject sequence is defined as the longest initial subsequence of the input wide-character string, starting with the first wide-character code that is not white space and is of the expected form. The subject sequence contains no wide-character codes if the input wide-character string is empty or consists entirely of white-space wide-character codes, or if the first wide-character code that is not white space is other than a sign or a permissible letter or digit.

> If the subject sequence has the expected form and base is 0, the sequence of wide-character codes starting with the first digit shall be interpreted as an integer constant. If the subject sequence has the expected form and the value of base is between 2 and 36, it shall be used as the base for conversion, ascribing to each letter its value as given above. If the subject sequence begins with a minus-sign, the value resulting from the conversion shall be negated. A pointer to the final wide-character string shall be stored in the object pointed to by endptr, provided that endptr is not a null pointer.

> In other than the C [CX] or POSIX locales, other implementation-defined subject sequences may be accepted.

> If the subject sequence is empty or does not have the expected form, no conversion shall be performed; the value of nptr shall be stored in the object pointed to by endptr, provided that endptr is not a null pointer.

> These functions shall not change the setting of errno if successful.

> Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and 0 is also a valid return on success, an application wishing to check for error situations should set errno to 0, then call wcstoul() or wcstoull(), then check errno.

#### RETURN VALUE

> Upon successful completion, the wcstoul() and wcstoull() functions shall return the converted value, if any. If no conversion could be performed, 0 shall be returned [CX] and errno may be set to indicate the error. If the correct value is outside the range of representable values, {ULONG_MAX} or {ULLONG_MAX} respectively shall be returned and errno set to [ERANGE].

#### ERRORS

> These functions shall fail if:

> [EINVAL]
>   [CX] The value of base is not supported.
> [ERANGE]
>   The value to be returned is not representable.

> These functions may fail if:

> [EINVAL]
>   [CX] No conversion could be performed.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> fscanf, iswalpha, wcstod, wcstol

> XBD <wchar.h>

#### CHANGE HISTORY

> First released in Issue 4. Derived from the MSE working draft.

#### Issue 5

> The DESCRIPTION is updated to indicate that errno is not changed if the function is successful.

#### Issue 6

> Extensions beyond the ISO C standard are marked.

> The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

> - The [EINVAL] error condition is added for when the value of base is not supported.

>   In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is added if no conversion could be performed.

> The following changes are made for alignment with the ISO/IEC 9899:1999 standard:

> - The wcstoul() prototype is updated.

> - The wcstoull() function is added.

#### Issue 7

> POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0727 [105] is applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]