| .\" Copyright (c) Bruno Haible <haible@clisp.cons.org> |
| .\" |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" References consulted: |
| .\" GNU glibc-2 source code and manual |
| .\" Dinkumware C library reference http://www.dinkumware.com/ |
| .\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html |
| .\" ISO/IEC 9899:1999 |
| .\" |
| .TH MBSTOWCS 3 1999-07-25 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| mbstowcs \- convert a multibyte string to a wide character string |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .sp |
| .BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n ); |
| .fi |
| .SH DESCRIPTION |
| If \fIdest\fP is not a NULL pointer, the \fBmbstowcs\fP() function converts the |
| multibyte string \fIsrc\fP to a wide-character string starting at \fIdest\fP. |
| At most \fIn\fP wide characters are written to \fIdest\fP. The conversion starts |
| in the initial state. The conversion can stop for three reasons: |
| .PP |
| 1. An invalid multibyte sequence has been encountered. In this case |
| (size_t)(\-1) is returned. |
| .PP |
| 2. \fIn\fP non-L'\\0' wide characters have been stored at \fIdest\fP. In this |
| case the number of wide characters written to \fIdest\fP is returned, but the |
| shift state at this point is lost. |
| .PP |
| 3. The multibyte string has been completely converted, including the |
| terminating '\\0'. In this case the number of wide characters written to |
| \fIdest\fP, excluding the terminating L'\\0' character, is returned. |
| .PP |
| The programmer must ensure that there is room for at least \fIn\fP wide |
| characters at \fIdest\fP. |
| .PP |
| If \fIdest\fP is NULL, \fIn\fP is ignored, and the conversion proceeds as |
| above, except that the converted wide characters are not written out to memory, |
| and that no length limit exists. |
| .PP |
| In order to avoid the case 2 above, the programmer should make sure \fIn\fP is |
| greater or equal to \fImbstowcs(NULL,src,0)+1\fP. |
| .SH "RETURN VALUE" |
| The \fBmbstowcs\fP() function returns the number of wide characters that make |
| up the converted part of the wide character string, not including the |
| terminating null wide character. If an invalid multibyte sequence was |
| encountered, (size_t)(\-1) is returned. |
| .SH "CONFORMING TO" |
| ISO/ANSI C, UNIX98 |
| .SH "SEE ALSO" |
| .BR mbsrtowcs (3) |
| .SH NOTES |
| The behaviour of \fBmbstowcs\fP() depends on the LC_CTYPE category of the |
| current locale. |
| .PP |
| The function \fBmbsrtowcs\fP() provides a better interface to the same |
| functionality. |