release/man3/mbsnrtowcs.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 .\" 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>
  17 .\"
  18 .TH MBSNRTOWCS 3  2011-10-01 "GNU" "Linux Programmer's Manual"
  19 .SH 名前
  20 mbsnrtowcs \- マルチバイト文字列をワイド文字列に変換する
  21 .SH 書式
  22 .nf
  23 .B #include <wchar.h>
  24 .sp
  25 .BI "size_t mbsnrtowcs(wchar_t *" dest ", const char **" src ,
  26 .BI "                  size_t " nms ", size_t " len ", mbstate_t *" ps );
  27 .fi
  28 .sp
  29 .in -4n
  30 glibc 向けの機能検査マクロの要件
  31 .RB ( feature_test_macros (7)
  32 参照):
  33 .in
  34 .sp
  35 .BR mbsnrtowcs ():
  36 .PD 0
  37 .ad l
  38 .RS 4
  39 .TP 4
  40 glibc 2.10 以降:
  41 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  42 .TP
  43 glibc 2.10 より前:
  44 _GNU_SOURCE
  45 .RE
  46 .ad
  47 .PD
  48 .SH 説明
  49 .BR mbsnrtowcs ()
  50 関数は
  51 .BR mbsrtowcs (3)
  52 関数に似ているが
  53 変換するバイト数が \fI*src\fP から始まる \fInms\fP バイトに制限されている
  54 点が異なっている。
  55 .PP
  56 \fIdest\fP が NULL ポインターでなければ
  57 .BR mbsnrtowcs ()
  58 関数は
  59 \fI*src\fP からのマルチバイト文字列の最大 \fInms\fP までを
  60 \fIdest\fP からのワイド文字列に変換する。
  61 最大 \fIlen\fP 文字のワイド文字が \fIdest\fP に書き込まれる。
  62 同時にシフト状態 \fI*ps\fP を更新する。
  63 変換は
  64 .I "mbrtowc(dest, *src, n, ps)"
  65 を、この呼び出しが成功する限り、繰り返し実行したのと実質的に同様である。
  66 ここでの \fIn\fP は正の数であり、繰り返しごとに \fIdest\fP が 1 増加させられ、
  67 \fI*src\fP が消費したバイト数だけ増加させられる。変換は以下の三つの
  68 いずれかの条件で停止する:
  69 .IP 1. 3
  70 不正なマルチバイト列に遭遇した。この場合には \fI*src\fP は不正な
  71 マルチバイト列を指すようにして、
  72 .I (size_t)\ \-1
  73 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
  74 .IP 2.
  75 \fInms\fP 制限によって強制的に停止するか、\fIlen\fP 文字の L\(aq\\0\(aq 以外の
  76 ワイド文字を \fIdest\fP に格納した場合。この場合は \fI*src\fP は
  77 次に変換されるマルチバイト列を指すようにして、\fIdest\fP に書き込まれた
  78 ワイド文字の数を返す。
  79 .IP 3.
  80 マルチバイト文字列が終端の NULL ワイド文字 (\(aq\\0\(aq)
  81 まで含めて完全に変換された場合。
  82 (この時、副作用として \fI*ps\fP が初期状態に戻される。)
  83 この場合は \fI*src\fP には NULL が設定され、
  84 \fIdest\fP に書き込まれた文字数 (終端の NULL ワイド文字は含まれない) を返す。
  85 .PP
  86 \fIdest\fP が NULL の場合、\fIlen\fP は無視され、上記と同様の変換が
  87 行われるが、変換されたワイド文字はメモリに書き込まれず、変換先の上限
  88 が存在しない。
  89 .PP
  90 上記のどちらの場合でも、\fIps\fP が NULL ポインターならば、代りに
  91 mbsnrtowcs 関数のみが使用する静的で名前のない状態が使用される。
  92 .PP
  93 プログラマーは \fIdest\fP に最低でも \fIlen\fP ワイド文字を書き込むこ
  94 とができる空間があることを保証しなければならない。
  95 .SH 返り値
  96 .BR mbsnrtowcs ()
  97 関数はワイド文字列に変換完了したワイド文字の数を返す。
  98 終端のナルワイド文字は含まない。不正なマルチバイト列に遭遇した場合には
  99 .I (size_t)\ \-1
 100 を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
 101 .SH 準拠
 102 POSIX.1-2008.
 103 .SH 注意
 104 .BR mbsnrtowcs ()
 105 の動作は現在のロケールの
 106 .B LC_CTYPE
 107 カテゴリに依存している。
 108 .PP
 109 \fIps\fP として NULL を渡すことはマルチスレッドでは安全でない。
 110 .SH 関連項目
 111 .BR iconv (3),
 112 .BR mbsrtowcs (3)