Standard C Library Functions wcstoul(3C)
NAME
wcstoul, wcstoull - convert wide-character string to
unsigned long
SYNOPSIS
#include
unsigned long wcstoul(const wchart *restrict nptr,
wchart **restrict endptr, int base);
unsigned long long wcstoull(const wchart *restrict nptr,
wchart **restrict endptr, int base);
DESCRIPTION
The wcstoul() and wcstoull() functions convert the initial
portion of the wide-character string pointed to by nptr to
unsigned long and unsigned long long representation, respec-
tively. First they decompose the input wide-character string
into three parts:
1. An initial, possibly empty, sequence of white-space
wide-character codes (as specified by the function
iswspace(3C))
2. Asubject 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
They then attempt to convert the subject sequence to an
unsigned integer and return the result.
If the value of base is 0, the expected form of the subject
sequence is that of a decimal constant, an octal constant,
or a hexadecimal constant, any of which may be preceded by a
`]' or a `-' 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 fol-
lowed by a sequence of the digits `0' to `7' only. A hexade-
cimal 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.
SunOS 5.11 Last change: 1 Nov 2003 1
Standard C Library Functions wcstoul(3C)
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 a `-' sign, but not includ-
ing 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 are
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 a 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 a
white space is other than a sign or a permissible letter or
digit.
If the subject sequence has the expected form and the value
of base is 0, the sequence of wide-character codes starting
with the first digit is interpreted as an integer constant.
If the subject sequence has the expected form and the value
of base is between 2 and 36, it is 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 is negated. A pointer to
the final wide character string is stored in the object
pointed to by endptr, provided that endptr is not a null
pointer.
If the subject sequence is empty or does not have the
expected form, no conversion is performed; the value of nptr
is stored in the object pointed to by endptr, provided that
endptr is not a null pointer.
The wcstoul() function does not change the setting of errno
if successful.
Since 0, {ULONGMAX}, and {ULONGMAX} are returned on error
and 0 is also a valid return on success, an application
wanting to check for error situations should set errno to 0,
then call wcstoul() or wcstoull(), then check errno.
SunOS 5.11 Last change: 1 Nov 2003 2
Standard C Library Functions wcstoul(3C)
The wcstoul() and wcstoull() functions do not change the
setting of errno if successful.
RETURN VALUE
Upon successful completion, wcstoul() and wcstoull() return
the converted value, if any. If no conversion could be per-
formed, 0 is returned and errno may be set to indicate the
error. If the correct value is outside the range of
representable values, {ULONGMAX} or {ULONGMAX}, respec-
tively, is returned and errno is set to ERANGE.
ERORS
The wcstoul() and wcstoull() functions will fail if:
EINVAL The value of base is not supported.
ERANGE The value to be returned is not representable.
The wcstoul() and wcstoull() functions may fail if:
EINVAL No conversion could be performed.
USAGE
Unlike wcstod(3C) and wcstol(3C), wcstoul() and wcstoull()
must always return a non-negative number; using the return
value of wcstoul() for out-of-range numbers with wcstoul()
or wcstoull() could cause more severe problems than just
loss of precision if those numbers can ever be negative.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
isspace(3C), iswalpha(3C), scanf(3C), wcstod(3C),
wcstol(3C), attributes(5), standards(5)
SunOS 5.11 Last change: 1 Nov 2003 3
|
