1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
3 .\" This is free documentation; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
8 .\" References consulted:
9 .\" GNU glibc-2 source code and manual
10 .\" Dinkumware C library reference http://www.dinkumware.com/
11 .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
13 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
14 .\" all rights reserved.
15 .\" Translated Tue Jan 11 00:56:10 JST 2000
16 .\" by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
18 .TH MBSNRTOWCS 3 2011-10-01 "GNU" "Linux Programmer's Manual"
21 .\"O mbsnrtowcs \- convert a multibyte string to a wide-character string
22 mbsnrtowcs \- マルチバイト文字列をワイド文字列に変換する
28 .BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src ,
29 .BI " size_t " nms ", size_t " len ", mbstate_t *" ps );
33 .\"O Feature Test Macro Requirements for glibc (see
34 .\"O .BR feature_test_macros (7)):
36 .RB ( feature_test_macros (7)
45 .\"O Since glibc 2.10:
47 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
49 .\"O Before glibc 2.10:
58 .\"O .BR mbsnrtowcs ()
59 .\"O function is like the
60 .\"O .BR mbsrtowcs (3)
61 .\"O function, except that
62 .\"O the number of bytes to be converted, starting at \fI*src\fP, is limited to
68 変換するバイト数が \fI*src\fP から始まる \fInms\fP バイトに制限されている
71 .\"O If \fIdest\fP is not a NULL pointer, the
72 .\"O .BR mbsnrtowcs ()
73 .\"O function converts at
74 .\"O most \fInms\fP bytes from the
75 .\"O multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP.
76 .\"O At most \fIlen\fP wide characters are written to \fIdest\fP.
78 .\"O \fI*ps\fP is updated.
79 .\"O The conversion is effectively performed by repeatedly
81 .\"O .I "mbrtowc(dest, *src, n, ps)"
82 .\"O where \fIn\fP is some
83 .\"O positive number, as long as this call succeeds, and then incrementing
84 .\"O \fIdest\fP by one and \fI*src\fP by the number of bytes consumed.
86 .\"O conversion can stop for three reasons:
87 \fIdest\fP が NULL ポインターでなければ
90 \fI*src\fP からのマルチバイト文字列の最大 \fInms\fP までを
91 \fIdest\fP からのワイド文字列に変換する。
92 最大 \fIlen\fP 文字のワイド文字が \fIdest\fP に書き込まれる。
93 同時にシフト状態 \fI*ps\fP を更新する。
95 .I "mbrtowc(dest, *src, n, ps)"
96 を、この呼び出しが成功する限り、繰り返し実行したのと実質的に同様である。
97 ここでの \fIn\fP は正の数であり、繰り返しごとに \fIdest\fP が 1 増加させられ、
98 \fI*src\fP が消費したバイト数だけ増加させられる。変換は以下の三つの
101 .\"O An invalid multibyte sequence has been encountered.
102 .\"O In this case \fI*src\fP
103 .\"O is left pointing to the invalid multibyte sequence,
104 .\"O .I (size_t)\ \-1
106 .\"O and \fIerrno\fP is set to \fBEILSEQ\fP.
107 不正なマルチバイト列に遭遇した。この場合には \fI*src\fP は不正な
110 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
112 .\"O The \fInms\fP limit forces a stop,
113 .\"O or \fIlen\fP non-L\(aq\\0\(aq wide characters
114 .\"O have been stored at \fIdest\fP.
115 .\"O In this case \fI*src\fP is left pointing to the
116 .\"O next multibyte sequence to be converted, and the number of wide characters
117 .\"O written to \fIdest\fP is returned.
118 \fInms\fP 制限によって強制的に停止するか、\fIlen\fP 文字の L\(aq\\0\(aq 以外の
119 ワイド文字を \fIdest\fP に格納した場合。この場合は \fI*src\fP は
120 次に変換されるマルチバイト列を指すようにして、\fIdest\fP に書き込まれた
123 .\"O The multibyte string has been completely converted, including the
124 .\"O terminating null wide character (\(aq\\0\(aq)
125 .\"O (which has the side effect of bringing back \fI*ps\fP to the
127 .\"O In this case \fI*src\fP is set to NULL, and the number of wide
128 .\"O characters written to \fIdest\fP,
129 .\"O excluding the terminating null wide character,
131 マルチバイト文字列が終端の NULL ワイド文字 (\(aq\\0\(aq)
133 (この時、副作用として \fI*ps\fP が初期状態に戻される。)
134 この場合は \fI*src\fP には NULL が設定され、
135 \fIdest\fP に書き込まれた文字数 (終端の NULL ワイド文字は含まれない) を返す。
137 .\"O If \fIdest\fP is NULL, \fIlen\fP is ignored, and the conversion proceeds as
138 .\"O above, except that the converted wide characters
139 .\"O are not written out to memory,
140 .\"O and that no destination length limit exists.
141 \fIdest\fP が NULL の場合、\fIlen\fP は無視され、上記と同様の変換が
142 行われるが、変換されたワイド文字はメモリに書き込まれず、変換先の上限
145 .\"O In both of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
146 .\"O state only known to the mbsnrtowcs function is used instead.
147 上記のどちらの場合でも、\fIps\fP が NULL ポインターならば、代りに
148 mbsnrtowcs 関数のみが使用する静的で名前のない状態が使用される。
150 .\"O The programmer must ensure that there is room for at least \fIlen\fP wide
151 .\"O characters at \fIdest\fP.
152 プログラマーは \fIdest\fP に最低でも \fIlen\fP ワイド文字を書き込むこ
153 とができる空間があることを保証しなければならない。
154 .\"O .SH "RETURN VALUE"
157 .\"O .BR mbsnrtowcs ()
158 .\"O function returns the number of wide characters
159 .\"O that make up the converted part of the wide-character string,
160 .\"O not including the terminating null wide character.
161 .\"O If an invalid multibyte sequence was
163 .\"O .I (size_t)\ \-1
164 .\"O is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
166 関数はワイド文字列に変換完了したワイド文字の数を返す。
167 終端のナルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には
169 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
170 .\"O .SH "CONFORMING TO"
176 .\"O .BR mbsnrtowcs ()
186 .\"O Passing NULL as \fIps\fP is not multithread safe.
187 \fIps\fP として NULL を渡すことはマルチスレッドでは安全でない。