version 1.7, 2004/01/21 12:40:14 |
version 1.8, 2004/01/24 16:58:54 |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Fn mbsrtowcs |
.Fn mbsrtowcs |
converts the multibyte character string indirectly pointed by |
converts the multibyte character string indirectly pointed to by |
.Fa s |
.Fa s |
to the corresponding wide character string, and stores it to the |
to the corresponding wide character string, and stores it in the |
array pointed by |
array pointed to by |
.Fa pwcs . |
.Fa pwcs . |
The conversion stops due to the following reasons: |
The conversion stops due to the following reasons: |
.Bl -bullet |
.Bl -bullet |
Line 72 is continuously called. |
|
Line 72 is continuously called. |
|
After conversion, |
After conversion, |
if |
if |
.Fa pwcs |
.Fa pwcs |
is not NULL pointer, |
is not a |
the pointer object pointed by |
.Dv NULL |
|
pointer, |
|
the pointer object pointed to by |
.Fa s |
.Fa s |
is NULL pointer (if the conversion is stopped due to reach a null byte) |
is a |
|
.Dv NULL |
|
pointer (if the conversion is stopped due to reaching a null byte) |
or the first byte of the character just after the last character converted. |
or the first byte of the character just after the last character converted. |
.Pp |
.Pp |
If |
If |
.Fa pwcs |
.Fa pwcs |
is not null pointer and the conversion is stopped due to reach |
is not a |
|
.Dv NULL |
|
pointer and the conversion is stopped due to reaching |
a null byte, the |
a null byte, the |
.Fn mbsrtowcs |
.Fn mbsrtowcs |
places the state object pointed by |
places the state object pointed to by |
.Fa ps |
.Fa ps |
to an initial state after the conversion is taken place. |
to an initial state after the conversion has taken place. |
.Pp |
.Pp |
The behaviour of the |
The behaviour of |
.Fn mbsrtowcs |
.Fn mbsrtowcs |
is affected by LC_CTYPE category of the current locale. |
is affected by the |
|
.Dv LC_CTYPE |
|
category of the current locale. |
.Pp |
.Pp |
There are special cases: |
These are the special cases: |
.Bl -tag -width 012345678901 |
.Bl -tag -width 012345678901 |
.It "s == NULL || *s == NULL" |
.It "s == NULL || *s == NULL" |
undefined (may causes the program to crash). |
Undefined (may cause the program to crash). |
.It "pwcs == NULL" |
.It "pwcs == NULL" |
The conversion is taken place, but the result wide character string |
The conversion has taken place, but the resulting wide character string |
is discarded. |
was discarded. |
In this case, the pointer object pointed by |
In this case, the pointer object pointed to by |
.Fa s |
.Fa s |
is not modified and |
is not modified and |
.Fa n |
.Fa n |
|
|
.Fa ps |
.Fa ps |
mentioned in this manual page. |
mentioned in this manual page. |
.Pp |
.Pp |
Calling any other functions in the |
Calling any other functions in |
.Lb libc |
.Lb libc |
never change the internal |
never changes the internal state of |
state of the |
|
.Fn mbsrtowcs , |
.Fn mbsrtowcs , |
that is initialized at startup time of the program. |
which is initialized at startup time of the program. |
.El |
.El |
.\" ---------------------------------------------------------------------- |
.\" ---------------------------------------------------------------------- |
.Sh RETURN VALUES |
.Sh RETURN VALUES |
The |
|
.Fn mbsrtowcs |
.Fn mbsrtowcs |
returns |
returns: |
.Bl -tag -width 012345678901 |
.Bl -tag -width 012345678901 |
.It 0 or positive |
.It 0 or positive |
The value returned is the number of elements stored to the array pointed by |
The value returned is the number of elements stored in the array |
|
pointed to by |
.Fa pwcs , |
.Fa pwcs , |
except for a terminate null wide character (if any). |
except for a terminating null wide character (if any). |
If |
If |
.Fa pwcs |
.Fa pwcs |
is not null and the value returned is equal to |
is not null and the value returned is equal to |
.Fa n , |
.Fa n , |
the wide character string pointed by |
the wide character string pointed to by |
.Fa pwcs |
.Fa pwcs |
is not null terminated. |
is not null terminated. |
If |
If |
.Fa pwcs |
.Fa pwcs |
is a null pointer, the value returned is the number of elements to contain |
is a null pointer, the value returned is the number of elements to contain |
the whole string converted, except for a terminate null wide character. |
the whole string converted, except for a terminating null wide character. |
.It (size_t)-1 |
.It (size_t)-1 |
The array indirectly pointed by |
The array indirectly pointed to by |
.Fa s |
.Fa s |
contains a byte sequence forming invalid character. |
contains a byte sequence forming invalid character. |
In this case, the |
In this case, |
.Fn mbsrtowcs |
.Fn mbsrtowcs |
sets errno to indicate the error. |
sets |
|
.Va errno |
|
to indicate the error. |
.El |
.El |
.\" ---------------------------------------------------------------------- |
.\" ---------------------------------------------------------------------- |
.Sh ERRORS |
.Sh ERRORS |
The |
|
.Fn mbsrtowcs |
.Fn mbsrtowcs |
may causes an error in the following case: |
may cause an error in the following case: |
.Bl -tag -width Er |
.Bl -tag -width Er |
.It Bq Er EILSEQ |
.It Bq Er EILSEQ |
The pointer pointed by |
The pointer pointed to by |
.Fa s |
.Fa s |
points an invalid or incomplete multibyte character. |
points to an invalid or incomplete multibyte character. |
.It Bq Er EINVAL |
.It Bq Er EINVAL |
.Fa ps |
.Fa ps |
points an invalid or uninitialized mbstate_t object. |
points to an invalid or uninitialized mbstate_t object. |
.El |
.El |
.\" ---------------------------------------------------------------------- |
.\" ---------------------------------------------------------------------- |
.Sh SEE ALSO |
.Sh SEE ALSO |