draft/man3/wcsnrtombs.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 .\"
  13 .\" About this Japanese page, please contact to JM Project <JM@linux.or.jp>
  14 .\" Translated Fri Oct 22 01:12:12 JST 1999
  15 .\"           by FUJIWARA Teruyoshi <fujiwara@linux.or.jp>
  16 .\"
  17 .TH WCSNRTOMBS 3  2011-10-01 "GNU" "Linux Programmer's Manual"
  18 .\"O .SH NAME
  19 .SH 名前
  20 .\"O wcsnrtombs \- convert a wide-character string to a multibyte string
  21 wcsnrtombs \- ワイド文字文字列をマルチバイト文字列に変換する
  22 .\"O .SH SYNOPSIS
  23 .SH 書式
  24 .nf
  25 .B #include <wchar.h>
  26 .sp
  27 .BI "size_t wcsnrtombs(char *" dest ", const wchar_t **" src ", size_t " nwc ,
  28 .BI "                  size_t " len ", mbstate_t *" ps );
  29 .fi
  30 .sp
  31 .in -4n
  32 .\"O Feature Test Macro Requirements for glibc (see
  33 .\"O .BR feature_test_macros (7)):
  34 glibc 向けの機能検査マクロの要件
  35 .RB ( feature_test_macros (7)
  36 参照):
  37 .in
  38 .sp
  39 .BR wcsnrtombs ():
  40 .PD 0
  41 .ad l
  42 .RS 4
  43 .TP 4
  44 .\"O Since glibc 2.10:
  45 glibc 2.10 以降:
  46 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  47 .TP
  48 .\"O Before glibc 2.10:
  49 glibc 2.10 より前:
  50 _GNU_SOURCE
  51 .RE
  52 .ad
  53 .PD
  54 .\"O .SH DESCRIPTION
  55 .SH 説明
  56 .\"O The
  57 .\"O .BR wcsnrtombs ()
  58 .\"O function is like the
  59 .\"O .BR wcsrtombs (3)
  60 .\"O function,
  61 .\"O except that the number of wide characters to be converted,
  62 .\"O starting at \fI*src\fP, is limited to \fInwc\fP.
  63 .BR wcsnrtombs ()
  64 関数は、
  65 .BR wcsrtombs ()
  66 関数に似ている。ただし、
  67 変換されるワイド文字の数が(\fI*src\fP から数えて) \fInwc\fP 文字に制限
  68 されている点が異なる。
  69 .PP
  70 .\"O If \fIdest\fP is not a NULL pointer,
  71 .\"O the
  72 .\"O .BR wcsnrtombs ()
  73 .\"O function converts
  74 .\"O at most \fInwc\fP wide characters from
  75 .\"O the wide-character string \fI*src\fP to a multibyte string starting at
  76 .\"O \fIdest\fP.
  77 .\"O At most \fIlen\fP bytes are written to \fIdest\fP.
  78 .\"O The shift state
  79 .\"O \fI*ps\fP is updated.
  80 .\"O The conversion is effectively performed by repeatedly
  81 .\"O calling
  82 .\"O .IR "wcrtomb(dest, *src, ps)" ,
  83 .\"O as long as this call succeeds,
  84 .\"O and then incrementing \fIdest\fP by the
  85 .\"O number of bytes written and \fI*src\fP
  86 .\"O by one.
  87 .\"O The conversion can stop for three reasons:
  88 \fIdest\fP が NULL ポインタでなければ、
  89 .BR wcsnrtombs ()
  90 関数は
  91 ワイド文字文字列の最大 \fInwc\fP 個までのワイド文字を \fIdest\fP から
  92 始まるマルチバイト文字列に変換する。\fIdest\fP には最大 \fIlen\fP バイ
  93 トまで書き込まれる。シフト状態 \fI*ps\fP は更新される。実際の効果とし
  94 ては、この変換は以下の動作と同じになる:
  95 .IR "wcrtomb(dest, *src, ps)"
  96 を呼び、成功が返ったら
  97 \fIdest\fP を書き込んだバイト数だけ増やし、\fI*src\fP を 1 増やす。
  98 そして、wcrtomb が成功を返す限りこれを繰り返す。
  99 変換が止まる理由は 3 つ考えられる:
 100 .PP
 101 .\"O 1. A wide character has been encountered that can not be represented as a
 102 .\"O multibyte sequence (according to the current locale).
 103 .\"O In this case \fI*src\fP
 104 .\"O is left pointing to the invalid wide character,
 105 .\"O .I (size_t)\ \-1
 106 .\"O is returned,
 107 .\"O and \fIerrno\fP is set to \fBEILSEQ\fP.
 108 1. (現在のロケールに基づいて)マルチバイト列で表現できないワイド文字に
 109 出会った場合。この場合は、\fI*src\fP は不正なワイド文字を指した状態になり、
 110 .I (size_t)\ \-1
 111 が返され、\fIerrno\fP に \fBEILSEQ\fP が設定される。
 112 .PP
 113 .\"O 2. \fInwc\fP wide characters have been
 114 .\"O- converted without encountering a L\(aq\\0\(aq,
 115 .\"O+ converted without encountering a null wide character (L\(aq\\0\(aq),
 116 .\"O or the length limit forces a stop.
 117 .\"O In this case \fI*src\fP is left pointing
 118 .\"O to the next wide character to be converted, and the number of bytes written
 119 .\"O to \fIdest\fP is returned.
 120 2. NULL ワイド文字 (L\(aq\\0\(aq) に出会わないで \fInwc\fP 個のワイド文字を
 121 変換した場合か、長さの制限によって変換が止められた場合。
 122 この場合には、\fI*src\fP は次に変換されるべきワイド文字を指した状態になり、
 123 \fIdest\fP に書き込まれたバイト数が返される。
 124 .PP
 125 .\"O 3. The wide-character string has been completely converted, including the
 126 .\"O- terminating L\(aq\\0\(aq (which has the side effect of bringing back \fI*ps\fP
 127 .\"O+ terminating null wide character (which has the side effect of bringing back \fI*ps\fP
 128 .\"O to the initial state).
 129 .\"O In this case \fI*src\fP is set to NULL, and the number
 130 .\"O- of bytes written to \fIdest\fP, excluding the terminating \(aq\\0\(aq byte, is
 131 .\"O+ of bytes written to \fIdest\fP, excluding the terminating null, is
 132 .\"O returned.
 133 3. ワイド文字列が終端の L\(aq\\0\(aq (これには \fI*ps\fP を初期状態に戻すと
 134 いう副作用がある)も含めて全て変換された場合。この場合には \fI*src\fP
 135 に NULL が設定され、\fIdest\fP に書き込まれたバイト数が返される
 136 (終端の \(aq\\0\(aq は数えない)。
 137 .PP
 138 .\"O If \fIdest\fP is NULL, \fIlen\fP is ignored,
 139 .\"O and the conversion proceeds as above,
 140 .\"O except that the converted bytes are not written out to memory, and that
 141 .\"O no destination length limit exists.
 142 \fIdest\fP が NULL ならば \fIlen\fP は無視されて前述のように変換が行わ
 143 れるが、変換されたバイトデータはメモリに書き出されない点と、出力先の長
 144 さの制限がない点が異なる。
 145 .PP
 146 .\"O In both of the above cases,
 147 .\"O if \fIps\fP is a NULL pointer, a static anonymous
 148 .\"O state only known to the wcsnrtombs function is used instead.
 149 上記のいずれの場合も、\fIps\fP が NULL ポインタならば、wcsnrtombs 関数
 150 だけが知っている静的な匿名の状態がシフト状態の代わりに用いられる。
 151 .PP
 152 .\"O The programmer must ensure that there is room for at least \fIlen\fP bytes
 153 .\"O at \fIdest\fP.
 154 プログラマは少なくとも \fIlen\fP バイトの領域を \fIdest\fP に確保しな
 155 ければならない。
 156 .\"O .SH "RETURN VALUE"
 157 .SH 返り値
 158 .\"O The
 159 .\"O .BR wcsnrtombs ()
 160 .\"O function returns
 161 .\"O the number of bytes that make up the
 162 .\"O converted part of multibyte sequence,
 163 .\"O not including the terminating null.
 164 .BR wcsnrtombs ()
 165 関数は、変換して得られたマルチバイト列のバイト数を返
 166 す。これには終端の NULL は含まない。
 167 .\"O If a wide character was encountered which
 168 .\"O could not be converted,
 169 .\"O .I (size_t)\ \-1
 170 .\"O is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
 171 変換できないワイド文字に出会った場合には
 172 .I (size_t)\ \-1
 173 が返され、 \fIerrno\fP に \fBEILSEQ\fP が設定される。
 174 .\"O .SH "CONFORMING TO"
 175 .SH 準拠
 176 POSIX.1-2008.
 177 .\"O .SH NOTES
 178 .SH 注意
 179 .\"O The behavior of
 180 .\"O .BR wcsnrtombs ()
 181 .\"O depends on the
 182 .\"O .B LC_CTYPE
 183 .\"O category of the
 184 .\"O current locale.
 185 .BR wcsnrtombs ()
 186 の動作は現在のロケールの
 187 .B LC_CTYPE
 188 カテゴリに依存する。
 189 .PP
 190 .\"O Passing NULL as \fIps\fP is not multithread safe.
 191 \fIps\fP に NULL を渡した際の動作はマルチスレッドセーフでない。
 192 .\"O .SH "SEE ALSO"
 193 .SH 関連項目
 194 .BR iconv (3),
 195 .BR wcsrtombs (3)