mirror of https://github.com/mkerrisk/man-pages
160 lines
6.0 KiB
Plaintext
160 lines
6.0 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "WCSTOUL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" wcstoul
|
||
|
.SH NAME
|
||
|
wcstoul, wcstoull \- convert a wide-character string to an unsigned
|
||
|
long
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <wchar.h>
|
||
|
.br
|
||
|
.sp
|
||
|
unsigned long wcstoul(const wchar_t *restrict\fP \fInptr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB);
|
||
|
.br
|
||
|
unsigned long long wcstoull(const wchar_t *restrict\fP \fInptr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ wchar_t **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIwcstoul\fP() and \fIwcstoull\fP() functions shall convert the
|
||
|
initial portion of the wide-character string pointed to
|
||
|
by \fInptr\fP to \fBunsigned long\fP and \fBunsigned long long\fP
|
||
|
representation, respectively. First, they shall decompose the
|
||
|
input wide-character string into three parts:
|
||
|
.IP " 1." 4
|
||
|
An initial, possibly empty, sequence of white-space wide-character
|
||
|
codes (as specified by \fIiswspace\fP())
|
||
|
.LP
|
||
|
.IP " 2." 4
|
||
|
A subject sequence interpreted as an integer represented in some radix
|
||
|
determined by the value of \fIbase\fP
|
||
|
.LP
|
||
|
.IP " 3." 4
|
||
|
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
|
||
|
.LP
|
||
|
.LP
|
||
|
Then they shall attempt to convert the subject sequence to an unsigned
|
||
|
integer, and return the result.
|
||
|
.LP
|
||
|
If \fIbase\fP 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 \fB'+'\fP or \fB'-'\fP
|
||
|
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 \fB'0'\fP optionally followed by a sequence
|
||
|
of the digits \fB'0'\fP to \fB'7'\fP only. A hexadecimal constant
|
||
|
consists of the prefix 0x or 0X followed by a sequence of
|
||
|
the decimal digits and letters \fB'a'\fP (or \fB'A'\fP ) to \fB'f'\fP
|
||
|
(or \fB'F'\fP ) with values 10 to 15
|
||
|
respectively.
|
||
|
.LP
|
||
|
If the value of \fIbase\fP 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 \fIbase\fP, optionally
|
||
|
preceded by a \fB'+'\fP or \fB'-'\fP sign, but
|
||
|
not including an integer suffix. The letters from \fB'a'\fP (or \fB'A'\fP
|
||
|
) to \fB'z'\fP (or \fB'Z'\fP ) inclusive are
|
||
|
ascribed the values 10 to 35; only letters whose ascribed values are
|
||
|
less than that of \fIbase\fP shall be permitted. If the value
|
||
|
of \fIbase\fP is 16, the wide-character codes 0x or 0X may optionally
|
||
|
precede the sequence of letters and digits, following the
|
||
|
sign if present.
|
||
|
.LP
|
||
|
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.
|
||
|
.LP
|
||
|
If the subject sequence has the expected form and \fIbase\fP 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 \fIbase\fP 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 \fIendptr\fP, provided
|
||
|
that \fIendptr\fP is not a null pointer.
|
||
|
.LP
|
||
|
In other than the C \ or POSIX locales, other
|
||
|
implementation-defined subject sequences may be accepted.
|
||
|
.LP
|
||
|
If the subject sequence is empty or does not have the expected form,
|
||
|
no conversion shall be performed; the value of \fInptr\fP
|
||
|
shall be stored in the object pointed to by \fIendptr\fP, provided
|
||
|
that \fIendptr\fP is not a null pointer.
|
||
|
.LP
|
||
|
The
|
||
|
\fIwcstoul\fP() function shall not change the setting of \fIerrno\fP
|
||
|
if successful.
|
||
|
.LP
|
||
|
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 \fIerrno\fP to 0, then call
|
||
|
\fIwcstoul\fP() or \fIwcstoull\fP(), then check \fIerrno\fP.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, the \fIwcstoul\fP() and \fIwcstoull\fP()
|
||
|
functions shall return the converted value, if any. If no
|
||
|
conversion could be performed, 0 shall be returned \ and \fIerrno\fP
|
||
|
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 \fIerrno\fP
|
||
|
set to [ERANGE].
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
These functions shall fail if:
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The value of \fIbase\fP is not supported.
|
||
|
.TP 7
|
||
|
.B ERANGE
|
||
|
The value to be returned is not representable.
|
||
|
.sp
|
||
|
.LP
|
||
|
These functions may fail if:
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
No
|
||
|
conversion could be performed.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIiswalpha\fP() , \fIscanf\fP() , \fIwcstod\fP() , \fIwcstol\fP()
|
||
|
, the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<wchar.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|