2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "WCSTOL" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" wcstol
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
wcstol, wcstoll \- convert a wide-character string to a long integer
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <wchar.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
long wcstol(const wchar_t *restrict\fP \fInptr\fP\fB, wchar_t **restrict\fP
|
|
|
|
\fIendptr\fP\fB,
|
|
|
|
.br
|
|
|
|
\ \ \ \ \ \ int\fP \fIbase\fP\fB);
|
|
|
|
.br
|
|
|
|
long long wcstoll(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
|
|
|
|
These functions shall convert the initial portion of the wide-character
|
|
|
|
string pointed to by \fInptr\fP to \fBlong\fP, \fBlong
|
|
|
|
long\fP, \fBunsigned long\fP, and \fBunsigned long long\fP representation,
|
|
|
|
respectively. First, they shall decompose the input
|
|
|
|
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 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 code representations of 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
|
|
|
|
non-white-space wide-character code that 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 code, or if the first non-white-space
|
|
|
|
wide-character code 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
|
2007-11-18 06:52:48 +00:00
|
|
|
In other than the C or POSIX locales, other
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
|
|
|
These functions shall not change the setting of \fIerrno\fP if successful.
|
|
|
|
.LP
|
|
|
|
Since 0, {LONG_MIN} or {LLONG_MIN} and {LONG_MAX} or {LLONG_MAX} are
|
|
|
|
returned on error and are also valid returns on success, an
|
|
|
|
application wishing to check for error situations should set \fIerrno\fP
|
|
|
|
to 0, then call \fIwcstol\fP() or \fIwcstoll\fP(), then
|
|
|
|
check \fIerrno\fP.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
|
|
|
Upon successful completion, these functions shall return the converted
|
|
|
|
value, if any. If no conversion could be performed, 0
|
2007-11-18 06:52:48 +00:00
|
|
|
shall be returned and \fIerrno\fP may be set to indicate the error.
|
2004-11-03 13:51:07 +00:00
|
|
|
If the correct value is outside the range of representable values,
|
|
|
|
{LONG_MIN}, {LONG_MAX}, {LLONG_MIN}, or {LLONG_MAX} shall
|
|
|
|
be returned (according to the sign of the value), 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
|
2007-09-20 06:11:55 +00:00
|
|
|
\fIiswalpha\fP(), \fIscanf\fP(), \fIwcstod\fP(), the Base Definitions
|
2004-11-03 13:51:07 +00:00
|
|
|
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 .
|