.\" 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
.\"
.\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated Tue Jan 11 00:56:04 JST 2000
.\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\"
.TH MBSTOWCS 3 1999-07-25 "GNU" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O mbstowcs \- convert a multibyte string to a wide-character string
mbstowcs \- マルチバイト文字列をワイド文字列に変換する
.\"O .SH SYNOPSIS
.SH 書式
.nf
.B #include <stdlib.h>
.sp
.BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n );
.fi
.\"O .SH DESCRIPTION
.SH 説明
.\"O If \fIdest\fP is not a NULL pointer, the
.\"O .BR mbstowcs ()
.\"O function converts the
.\"O multibyte string \fIsrc\fP to a wide-character string starting at \fIdest\fP.
.\"O At most \fIn\fP wide characters are written to \fIdest\fP.
.\"O The conversion starts
.\"O in the initial state.
.\"O The conversion can stop for three reasons:
\fIdest\fP が NULL ポインターでなければ
.BR mbstowcs ()
関数は
マルチバイト文字列 \fI*src\fP を \fIdest\fP から始まるワイド文字列に
変換する。\fIdest\fP には最大で \fIn\fP 文字のワイド文字が
書き込まれる。変換は初期状態で開始され、
以下の三つのいずれかの条件で停止する:
.IP 1. 3
.\"O An invalid multibyte sequence has been encountered.
.\"O In this case
.\"O .I (size_t)\ \-1
.\"O is returned.
不正なマルチバイト列に遭遇した。この場合には
.I (size_t)\ \-1
を返す。
.IP 2.
.\"O \fIn\fP non-L\(aq\\0\(aq wide characters have been stored at \fIdest\fP.
.\"O In this
.\"O case the number of wide characters written to \fIdest\fP is returned, but the
.\"O shift state at this point is lost.
\fIn\fP 文字の L\(aq\\0\(aq 以外のワイド文字を \fIdest\fP に格納した場合。
この場合は \fI*src\fP が次に変換されるマルチバイト列を指すようにして、
\fIdest\fP に書き込まれたワイド文字の数を返す。しかしこの指している
場所のシフト状態は失われる。
.IP 3.
.\"O The multibyte string has been completely converted, including the
.\"O terminating \(aq\\0\(aq.
.\"O In this case the number of wide characters written to
.\"O \fIdest\fP, excluding the terminating L\(aq\\0\(aq character, is returned.
マルチバイト文字列が終端の \(aq\\0\(aq まで含めて完全に変換された場合。
この場合は終端の L\(aq\\0\(aq 文字を除いて
\fIdest\fP に書き込まれた文字数を返す。
.PP
.\"O The programmer must ensure that there is room for at least \fIn\fP wide
.\"O characters at \fIdest\fP.
プログラマーは \fIdest\fP に最低でも \fIn\fP ワイド文字を書き込むこ
とができる空間があることを保証しなければならない。
.PP
.\"O If \fIdest\fP is NULL, \fIn\fP is ignored, and the conversion proceeds as
.\"O above, except that the converted wide characters are not written out to memory,
.\"O and that no length limit exists.
\fIdest\fP が NULL の場合、\fIn\fP は無視され、上記と同様の変換が
行われるが、変換されたワイド文字はメモリに書き込まれず、変換先の上限
が存在しない。
.PP
.\"O In order to avoid the case 2 above, the programmer should make sure \fIn\fP is
.\"O greater or equal to \fImbstowcs(NULL,src,0)+1\fP.
上記の 2. の場合を避けるためにプログラマーは \fIn\fP が
\fImbstowcs(NULL,src,0)+1\fP 以上であることを保証すべきである。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O The
.\"O .BR mbstowcs ()
.\"O function returns the number of wide characters that make
.\"O up the converted part of the wide-character string, not including the
.\"O terminating null wide character.
.\"O If an invalid multibyte sequence was
.\"O encountered,
.\"O .I (size_t)\ \-1
.\"O is returned.
.BR mbstowcs ()
関数はワイド文字列に変換完了したワイド文字の数を返す。
終端のナルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には
.I (size_t)\ \-1
を返す。
.\"O .SH "CONFORMING TO"
.SH 準拠
C99.
.\"O .SH NOTES
.SH 注意
.\"O The behavior of
.\"O .BR mbstowcs ()
.\"O depends on the
.\"O .B LC_CTYPE
.\"O category of the
.\"O current locale.
.BR mbstowcs ()
の動作は現在のロケールの
.B LC_CTYPE
カテゴリに依存している。
.PP
.\"O The function
.\"O .BR mbsrtowcs (3)
.\"O provides a better interface to the same
.\"O functionality.
.BR mbsrtowcs (3)
関数は同じ機能のより良いインターフェースを提供する。
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR mbsrtowcs (3)