release/man3/mbrtowc.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
  12 .\"      http://www.UNIX-systems.org/online.html
  13 .\"   ISO/IEC 9899:1999
  14 .\"
  15 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  16 .\"         all rights reserved.
  17 .\" Translated Tue Jan 11 00:56:16 JST 2000
  18 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  19 .\" Updated Thu Dec 13 JST 2001 by Kentaro Shirakata <argrath@ub32.org>
  20 .\"
  21 .TH MBRTOWC 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  22 .SH 名前
  23 mbrtowc \- マルチバイト列をワイド文字に変換する
  24 .SH 書式
  25 .nf
  26 .B #include <wchar.h>
  27 .sp
  28 .BI "size_t mbrtowc(wchar_t *" pwc ", const char *" s ", size_t " n \
  29 ", mbstate_t *" ps );
  30 .fi
  31 .SH 説明
  32 この関数が用いられる場合、通常 \fIs\fP が NULL でなく \fIpwc\fP も NULL で
  33 ない。この場合は、
  34 .BR mbrtowc ()
  35 関数は \fIs\fP から始まる最大 \fIn\fP バイトの
  36 マルチバイト文字を検査して、次の完全なマルチバイト文字列を取り出し、
  37 それをワイド文字に変換して \fI*pwc\fP に格納する。
  38 同時にシフト状態 \fI*ps\fP を更新する。
  39 変換したワイド文字が L\(aq\\0\(aq (NULL ワイド文字) でなければ、
  40 \fIs\fP から消費するバイト数を返す。
  41 変換したワイド文字が L\(aq\\0\(aq の場合にはシフト状態 \fI*ps\fP を
  42 初期状態に戻して 0 を返す。
  43 .PP
  44 \fIs\fP から始まる \fIn\fP バイトが完全なマルチバイト文字を含んでいない
  45 場合には、
  46 .BR mbrtowc ()
  47 は \fI(size_t)\ \-2\fP を返す。
  48 マルチバイト文字列に冗長なシフトシーケンスが含まれていると、
  49 \fIn\fP >= \fIMB_CUR_MAX\fP の時にもこのようなことが起こりえる。
  50 .PP
  51 \fIs\fP から始まるマルチバイト文字列が、次の完全な文字の前に
  52 不正なマルチバイト列を含んでいる場合には、
  53 .BR mbrtowc ()
  54 は
  55 \fI(size_t)\ \-1\fP を返し、\fIerrno\fP に \fBEILSEQ\fP を設定する。
  56 この場合は \fI*ps\fP への影響は未定義である。
  57 .PP
  58 \fIs\fP が NULL でなく \fIpwc\fP が NULL の場合は
  59 .BR mbrtowc ()
  60 関数は
  61 上記と同様に動作するが、変換したワイド文字はメモリには書き込まれない。
  62 .PP
  63 puts \fI*ps\fP in the initial state and returns 0.
  64 三番目の場合として \fIs\fP が NULL の場合、 \fIpwc\fP と \fIn\fP は
  65 無視される。
  66 \fI*ps\fP が表現する変換状態が不完全なマルチバイト文字変換を示している場合は、
  67 .BR mbrtowc ()
  68 関数は \fI(size_t)\ \-1\fP を返し、
  69 \fIerrno\fP に \fBEILSEQ\fP をセットし、
  70 \fI*ps\fP は未定義状態のままにする。
  71 さもなければ、
  72 .BR mbrtowc ()
  73 関数は \fI*ps\fP を初期状態にして 0 を返す。
  74 .PP
  75 上記の全ての場合において、\fIps\fP が NULL ポインターならば代わりに
  76 mbrtowc 関数のみが使用する静的で名前のない状態が使用される。
  77 さもなければ、\fI*ps\fP は有効な \fImbstate_t\fP オブジェクトで
  78 なければならない。
  79 \fImbstate_t\fP オブジェクトである \fIa\fP はゼロで埋めることによって
  80 初期状態に初期化できる。以下に例を示す。
  81 .sp
  82 .in +4n
  83 memset(&a, 0, sizeof(a));
  84 .in
  85 .SH 返り値
  86 L\(aq\\0\(aq 以外のワイド文字を認識した場合には
  87 .BR mbrtowc ()
  88 関数は \fIs\fP
  89 から始まるマルチバイト列から解析したバイト数を返す。
  90 L\(aq\\0\(aq ワイド文字を認識した場合には 0 を返す。
  91 不正なマルチバイト列に遭遇した場合には
  92 .I (size_t)\ \-1
  93 を返し、
  94 \fIerrno\fP に \fBEILSEQ\fP を設定する。完全なマルチバイト文字を
  95 解析できなかった場合には
  96 .I (size_t)\ \-2
  97 を返し \fIn\fP を増加させる必要があることを示す。
  98 .SH 準拠
  99 C99.
 100 .SH 注意
 101 .BR mbrtowc ()
 102 の動作は現在のロケールの
 103 .B LC_CTYPE
 104 カテゴリに依存している。
 105 .SH 関連項目
 106 .BR mbsrtowcs (3)