draft/man3/mbsrtowcs.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   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.
   7 .\"
   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
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  15 .\"         all rights reserved.
  16 .\" Translated Tue Jan 11 00:56:08 JST 2000
  17 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\"
  19 .TH MBSRTOWCS 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  20 .\"O .SH NAME
  21 .SH 名前
  22 .\"O mbsrtowcs \- convert a multibyte string to a wide-character string
  23 mbsrtowcs \- マルチバイト文字列をワイド文字列に変換する
  24 .\"O .SH SYNOPSIS
  25 .SH 書式
  26 .nf
  27 .B #include <wchar.h>
  28 .sp
  29 .BI "size_t mbsrtowcs(wchar_t *" dest ", const char **" src ,
  30 .BI "                  size_t " len ", mbstate_t *" ps );
  31 .fi
  32 .\"O .SH DESCRIPTION
  33 .SH 説明
  34 .\"O If \fIdest\fP is not a NULL pointer, the
  35 .\"O .BR mbsrtowcs ()
  36 .\"O function converts the
  37 .\"O multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP.
  38 .\"O At most \fIlen\fP wide characters are written to \fIdest\fP.
  39 .\"O The shift state
  40 .\"O \fI*ps\fP is updated.
  41 .\"O The conversion is effectively performed by repeatedly
  42 .\"O calling
  43 .\"O .I "mbrtowc(dest, *src, n, ps)"
  44 .\"O where \fIn\fP is some
  45 .\"O positive number, as long as this call succeeds, and then incrementing
  46 .\"O \fIdest\fP by one and \fI*src\fP by the number of bytes consumed.
  47 .\"O The conversion can stop for three reasons:
  48 \fIdest\fP が NULL ポインターでなければ、
  49 .BR mbsrtowcs ()
  50 関数は
  51 マルチバイト文字列 \fI*src\fP を \fIdest\fP から始まるワイド文字列に
  52 変換する。\fIdest\fP には最大で \fIlen\fP 文字のワイド文字が
  53 書き込まれる。同時にシフト状態 \fI*ps\fP を更新する。
  54 変換は
  55 .I "mbrtowc(dest, *src, n, ps)"
  56 を、この呼び出しが成功する限り繰り返し実行したのと実質的に同様である。
  57 ここで \fIn\fP は正の数であり、繰り返しごとに \fIdest\fP が 1 増加させられ、
  58 \fI*src\fP が消費したバイト数だけ増加させられる。変換は以下の三つの
  59 いずれかの条件で停止する:
  60 .IP 1. 3
  61 .\"O An invalid multibyte sequence has been encountered.
  62 .\"O In this case \fI*src\fP
  63 .\"O is left pointing to the invalid multibyte sequence,
  64 .\"O .I (size_t)\ \-1
  65 .\"O is returned,
  66 .\"O and \fIerrno\fP is set to \fBEILSEQ\fP.
  67 不正なマルチバイト列に遭遇した。この場合には \fI*src\fP は不正な
  68 マルチバイト列を指すようにして、
  69 .I (size_t)\ \-1
  70 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
  71 .IP 2.
  72 .\"O \fIlen\fP non-L\(aq\\0\(aq wide characters have been stored at \fIdest\fP.
  73 .\"O In this
  74 .\"O case \fI*src\fP is left pointing to the next
  75 .\"O multibyte sequence to be converted,
  76 .\"O and the number of wide characters written to \fIdest\fP is returned.
  77 \fIlen\fP 文字の L\(aq\\0\(aq 以外のワイド文字を \fIdest\fP に格納した場合。
  78 この場合は \fI*src\fP は次に変換されるマルチバイト列を指すようにして、
  79 \fIdest\fP に書き込まれたワイド文字の数を返す。
  80 .IP 3.
  81 .\"O The multibyte string has been completely converted, including the
  82 .\"O terminating null wide character (\(aq\\0\(aq), which has the side
  83 .\"O effect of bringing back \fI*ps\fP to the
  84 .\"O initial state.
  85 .\"O In this case \fI*src\fP is set to NULL, and the number of wide
  86 .\"O characters written to \fIdest\fP,
  87 .\"O excluding the terminating null wide character, is returned.
  88 マルチバイト文字列が終端の NULL ワイド文字 (\(aq\\0\(aq) まで含めて完全に
  89 変換された場合。この時、副作用として \fI*ps\fP が初期状態に戻される。
  90 この場合は \fI*src\fP には NULL が設定され、終端の NULL ワイド文字を除いて
  91 \fIdest\fP に書き込まれた文字数を返す。
  92 .PP
  93 .\"O If \fIdest\fP is NULL, \fIlen\fP is ignored,
  94 .\"O and the conversion proceeds as above,
  95 .\"O except that the converted wide characters are not written out to memory,
  96 .\"O and that no length limit exists.
  97 \fIdest\fP が NULL の場合、\fIlen\fP は無視され、上記と同様の変換が
  98 行われるが、変換されたワイド文字はメモリに書き込まれず、変換先の上限
  99 が存在しない。
 100 .PP
 101 .\"O In both of the above cases,
 102 .\"O if \fIps\fP is a NULL pointer, a static anonymous
 103 .\"O state only known to the
 104 .\"O .BR mbsrtowcs ()
 105 .\"O function is used instead.
 106 上記のどちらの場合でも、\fIps\fP が NULL ポインターならば、
 107 代りに
 108 .BR mbsrtowcs ()
 109 関数のみが使用する静的で名前のない状態が使用される。
 110 .PP
 111 .\"O The programmer must ensure that there is room for at least \fIlen\fP wide
 112 .\"O characters at \fIdest\fP.
 113 プログラマーは \fIdest\fP に最低でも \fIlen\fP ワイド文字を書き込むこ
 114 とができる空間があることを保証しなければならない。
 115 .\"O .SH "RETURN VALUE"
 116 .SH 返り値
 117 .\"O The
 118 .\"O .BR mbsrtowcs ()
 119 .\"O function returns the number of wide characters that make
 120 .\"O up the converted part of the wide-character string, not including the
 121 .\"O terminating null wide character.
 122 .\"O If an invalid multibyte sequence was
 123 .\"O encountered,
 124 .\"O .I (size_t)\ \-1
 125 .\"O is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
 126 .BR mbsrtowcs ()
 127 関数はワイド文字列に変換完了したワイド文字の数を返す。
 128 終端のナルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には
 129 .I (size_t)\ \-1
 130 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
 131 .\"O .SH "CONFORMING TO"
 132 .SH 準拠
 133 C99.
 134 .\"O .SH NOTES
 135 .SH 注意
 136 .\"O The behavior of
 137 .\"O .BR mbsrtowcs ()
 138 .\"O depends on the
 139 .\"O .B LC_CTYPE
 140 .\"O category of the
 141 .\"O current locale.
 142 .BR mbsrtowcs ()
 143 の動作は現在のロケールの
 144 .B LC_CTYPE
 145 カテゴリに依存している。
 146 .PP
 147 .\"O Passing NULL as \fIps\fP is not multithread safe.
 148 \fIps\fP として NULL を渡すことはマルチスレッドでは安全でない。
 149 .\"O .SH "SEE ALSO"
 150 .SH 関連項目
 151 .BR iconv (3),
 152 .BR mbsnrtowcs (3),
 153 .BR mbstowcs (3)