release/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 .SH 名前
  19 wcsnrtombs \- ワイド文字文字列をマルチバイト文字列に変換する
  20 .SH 書式
  21 .nf
  22 .B #include <wchar.h>
  23 .sp
  24 .BI "size_t wcsnrtombs(char *" dest ", const wchar_t **" src ", size_t " nwc ,
  25 .BI "                  size_t " len ", mbstate_t *" ps );
  26 .fi
  27 .sp
  28 .in -4n
  29 glibc 向けの機能検査マクロの要件
  30 .RB ( feature_test_macros (7)
  31 参照):
  32 .in
  33 .sp
  34 .BR wcsnrtombs ():
  35 .PD 0
  36 .ad l
  37 .RS 4
  38 .TP 4
  39 glibc 2.10 以降:
  40 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  41 .TP
  42 glibc 2.10 より前:
  43 _GNU_SOURCE
  44 .RE
  45 .ad
  46 .PD
  47 .SH 説明
  48 .BR wcsnrtombs ()
  49 関数は、
  50 .BR wcsrtombs ()
  51 関数に似ている。ただし、
  52 変換されるワイド文字の数が(\fI*src\fP から数えて) \fInwc\fP 文字に制限
  53 されている点が異なる。
  54 .PP
  55 \fIdest\fP が NULL ポインタでなければ、
  56 .BR wcsnrtombs ()
  57 関数は
  58 ワイド文字文字列の最大 \fInwc\fP 個までのワイド文字を \fIdest\fP から
  59 始まるマルチバイト文字列に変換する。\fIdest\fP には最大 \fIlen\fP バイ
  60 トまで書き込まれる。シフト状態 \fI*ps\fP は更新される。実際の効果とし
  61 ては、この変換は以下の動作と同じになる:
  62 .IR "wcrtomb(dest, *src, ps)"
  63 を呼び、成功が返ったら
  64 \fIdest\fP を書き込んだバイト数だけ増やし、\fI*src\fP を 1 増やす。
  65 そして、wcrtomb が成功を返す限りこれを繰り返す。
  66 変換が止まる理由は 3 つ考えられる:
  67 .PP
  68 1. (現在のロケールに基づいて)マルチバイト列で表現できないワイド文字に
  69 出会った場合。この場合は、\fI*src\fP は不正なワイド文字を指した状態になり、
  70 .I (size_t)\ \-1
  71 が返され、\fIerrno\fP に \fBEILSEQ\fP が設定される。
  72 .PP
  73 2. NULL ワイド文字 (L\(aq\\0\(aq) に出会わないで \fInwc\fP 個のワイド文字を
  74 変換した場合か、長さの制限によって変換が止められた場合。
  75 この場合には、\fI*src\fP は次に変換されるべきワイド文字を指した状態になり、
  76 \fIdest\fP に書き込まれたバイト数が返される。
  77 .PP
  78 3. ワイド文字列が終端の L\(aq\\0\(aq (これには \fI*ps\fP を初期状態に戻すと
  79 いう副作用がある)も含めて全て変換された場合。この場合には \fI*src\fP
  80 に NULL が設定され、\fIdest\fP に書き込まれたバイト数が返される
  81 (終端の \(aq\\0\(aq は数えない)。
  82 .PP
  83 \fIdest\fP が NULL ならば \fIlen\fP は無視されて前述のように変換が行わ
  84 れるが、変換されたバイトデータはメモリに書き出されない点と、出力先の長
  85 さの制限がない点が異なる。
  86 .PP
  87 上記のいずれの場合も、\fIps\fP が NULL ポインタならば、wcsnrtombs 関数
  88 だけが知っている静的な匿名の状態がシフト状態の代わりに用いられる。
  89 .PP
  90 プログラマは少なくとも \fIlen\fP バイトの領域を \fIdest\fP に確保しな
  91 ければならない。
  92 .SH 返り値
  93 .BR wcsnrtombs ()
  94 関数は、変換して得られたマルチバイト列のバイト数を返
  95 す。これには終端の NULL は含まない。
  96 変換できないワイド文字に出会った場合には
  97 .I (size_t)\ \-1
  98 が返され、 \fIerrno\fP に \fBEILSEQ\fP が設定される。
  99 .SH 準拠
 100 POSIX.1-2008.
 101 .SH 注意
 102 .BR wcsnrtombs ()
 103 の動作は現在のロケールの
 104 .B LC_CTYPE
 105 カテゴリに依存する。
 106 .PP
 107 \fIps\fP に NULL を渡した際の動作はマルチスレッドセーフでない。
 108 .SH 関連項目
 109 .BR iconv (3),
 110 .BR wcsrtombs (3)