wcstol(3C) wcstol(3C)
NAME
wcstol, wcstoul - convert wide character string to long integer
SYNOPSIS
#include <wchar.h>
long int wcstol(const wchart *nptr, wchart **endptr, int base);
unsigned long int wcstoul(const wchart *nptr, wchart **endptr,
int base);
DESCRIPTION
The wcstol() function converts the initial portion of the wide charac-
ter string pointed to by nptr to long int representation. First it
decomposes the input wide character string into three parts: an ini-
tial, possibly empty, sequence of white-space wide character codes (as
specified by the iswspace() function), a subject sequence interpreted
as an integer represented in some radix determined by the value of
base; and 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 it attempts to convert
the subject sequence to an integer, and returns the result. Because
zero, LONGMIN and LONGMAX are returned on error and are also valid
returns on success, an application wishing to check for error situa-
tions should set errno to 0, then call wcstol(), then check errno and
if it is zero, assume an error has occurred.
The wcstoul() function converts the initial portion of the wide char-
acter string pointed to by nptr to unsigned long int representation.
First it decomposes the input wide character string into three parts:
an initial possibly empty, sequence of white-space wide character
codes (as specified by the iswspace() function), a subject sequence
interpreted as an integer represented in some radix determined by the
value of base; and 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 it attempts to
convert the subject sequence to an integer, and returns the result.
Because zero and LONGMAX are returned on error and zero is also a
valid return on success, an application wishing to check for error
situations should set errno to 0, then call wcstoul(), then check
errno and if it is zero, assume an error has occurred. Unlike wcstod()
and wcstol(), wcstoul() must always return a non-negative number; so,
using the return value of wcstoul() for out-of-range numbers with
wcstoul() could cause more severe problems than just of precision if
those numbers can ever be negative.
If the value of base is zero, 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 decimal digits only. A hexadecimal constant
Page 1 Reliant UNIX 5.44 Printed 11/98
wcstol(3C) wcstol(3C)
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 respec-
tively.
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 with 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 permit-
ted. If the value of base is 16, the wide character code representa-
tions of 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 charac-
ter code that is not white-space and is of the expected form. The sub-
ject sequence contains no wide character codes if the input wide char-
acter string is empty or consists entirely of white-space wide charac-
ter codes, or if the first wide character code that is not white-space
is other than a sign or a permitted letter or digit.
If the subject sequence has the expected form and the value of base is
zero, 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 wcstol() and wcstoul() functions will fail if:
EINVAL The value of base is not supported.
ERANGE The value to be returned is not representable.
RESULT
Upon successful completion the wcstol() and wcstoul() functions return
the converted value, if any. If no conversion could be performed zero
is returned and errno may be set to indicate the error. If the correct
value is outside the range of the representable values, LONGMAX,
LONGMIN or ULONGMAX (according to the used function and the sign of
the value) is returned and errno is set to ERANGE.
SEE ALSO
iswalpha(3C), wcstod(3C), scanf(3S), wchar(5).
Page 2 Reliant UNIX 5.44 Printed 11/98