draft/man3/mbtowc.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:02 JST 2000
  17 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\"
  19 .TH MBTOWC 3  2011-09-28 "GNU" "Linux Programmer's Manual"
  20 .\"O .SH NAME
  21 .SH 名前
  22 .\"O mbtowc \- convert a multibyte sequence to a wide character
  23 mbtowc \- マルチバイト列をワイド文字に変換する
  24 .\"O .SH SYNOPSIS
  25 .SH 書式
  26 .nf
  27 .B #include <stdlib.h>
  28 .sp
  29 .BI "int mbtowc(wchar_t *" pwc ", const char *" s ", size_t " n );
  30 .fi
  31 .\"O .SH DESCRIPTION
  32 .SH 説明
  33 .\"O The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is
  34 .\"O not NULL.
  35 .\"O In this case, the
  36 .\"O .BR mbtowc ()
  37 .\"O function inspects at most \fIn\fP
  38 .\"O bytes of the multibyte string starting at \fIs\fP,
  39 .\"O extracts the next complete
  40 .\"O multibyte character, converts it to a wide character and stores it at
  41 .\"O \fI*pwc\fP.
  42 .\"O It updates an internal shift state only known to the mbtowc
  43 .\"O function.
  44 .\"O If \fIs\fP does not point to a null byte (\(aq\\0\(aq), it returns the number
  45 .\"O of bytes that were consumed from \fIs\fP, otherwise it returns 0.
  46 この関数が用いられる場合、通常 \fIs\fP が NULL でなく \fIpwc\fP も NULL
  47 でない。この場合は
  48 .BR mbtowc ()
  49 関数は \fIs\fP から始まる
  50 最大 \fIn\fP バイトのマルチバイト文字列を検査して、次の完全なマルチバイト
  51 文字を取り出し、それをワイド文字に変換して \fI*pwc\fP に格納する。
  52 同時に mbtowc 関数のみが使用する内部状態を更新する。\fIs\fP が NULL バイト
  53 (\(aq\\0\(aq) 以外を指している場合は、\fIs\fP から消費するバイト数を返す。
  54 \fIs\fP が NULL バイトを指している場合には 0 を返す。
  55 .PP
  56 .\"O If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
  57 .\"O character, or if they contain an invalid multibyte sequence,
  58 .\"O .BR mbtowc ()
  59 .\"O returns \-1.
  60 .\"O This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP,
  61 .\"O if the multibyte string contains redundant shift sequences.
  62 \fIs\fP から始まる \fIn\fP バイトが完全なマルチバイト文字を含んで
  63 いない場合や不正なマルチバイト列を含んでいる場合には
  64 .BR mbtowc ()
  65 は
  66 \-1 を返す。マルチバイト文字列に冗長なシフトシーケンスが
  67 含まれていると \fIn\fP >= \fIMB_CUR_MAX\fP の場合もこのようなことが
  68 起こりえる。
  69 .PP
  70 .\"O A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL.
  71 .\"O In this
  72 .\"O case the
  73 .\"O .BR mbtowc ()
  74 .\"O function behaves as above, except that it does not
  75 .\"O store the converted wide character in memory.
  76 \fIs\fP が NULL でなく \fIpwc\fP が NULL の場合は
  77 .BR mbtowc ()
  78 関数は
  79 上記と同様に動作するが、変換したワイド文字はメモリには書き込まれない。
  80 .PP
  81 .\"O A third case is when \fIs\fP is NULL.
  82 .\"O In this case, \fIpwc\fP and \fIn\fP are
  83 .\"O ignored.
  84 .\"O The
  85 .\"O .BR mbtowc ()
  86 .\"O function
  87 .\" The Dinkumware doc and the Single UNIX specification say this, but
  88 .\" glibc doesn't implement this.
  89 .\"O resets the shift state, only known to this function,
  90 .\"O to the initial state, and
  91 .\"O returns nonzero if the encoding has nontrivial shift state, or zero if the
  92 .\"O encoding is stateless.
  93 三番目の場合として \fIs\fP が NULL の場合は \fIpwc\fP と \fIn\fP は
  94 無視される。
  95 .BR mbtowc ()
  96 関数のみが使用するシフト状態は初期状態に
  97 戻される。そして文字符号がシフト状態に依存するならばゼロ以外を、文字符号が
  98 状態によらないならばゼロを返す。
  99 .\"O .SH "RETURN VALUE"
 100 .SH 返り値
 101 .\"O If \fIs\fP is not NULL, the
 102 .\"O .BR mbtowc ()
 103 .\"O function returns the number of
 104 .\"O consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte,
 105 .\"O or \-1 upon failure.
 106 \fIs\fP が NULL でなければ
 107 .BR mbtowc ()
 108 関数は \fIs\fP から消費した
 109 バイト数を、\fIs\fP がナル文字を指している場合はゼロを、
 110 変換に失敗した場合は \-1 を返す。
 111 .PP
 112 .\"O If \fIs\fP is NULL, the
 113 .\"O .BR mbtowc ()
 114 .\"O function
 115 .\"O returns nonzero if the encoding
 116 .\"O has nontrivial shift state, or zero if the encoding is stateless.
 117 \fIs\fP が NULL ならば
 118 .BR mbtowc ()
 119 関数は文字符号がシフト状態に依存
 120 していればゼロ以外を、状態によらなければゼロを返す。
 121 .\"O .SH "CONFORMING TO"
 122 .SH 準拠
 123 C99.
 124 .\"O .SH NOTES
 125 .SH 注意
 126 .\"O The behavior of
 127 .\"O .BR mbtowc ()
 128 .\"O depends on the
 129 .\"O .B LC_CTYPE
 130 .\"O category of the
 131 .\"O current locale.
 132 .BR mbtowc ()
 133 の動作は現在のロケールの
 134 .B LC_CTYPE
 135 カテゴリに依存している。
 136 .PP
 137 .\"O This function is not multithread safe.
 138 .\"O The function
 139 .\"O .BR mbrtowc (3)
 140 .\"O provides
 141 .\"O a better interface to the same functionality.
 142 この関数はマルチスレッドでは安全ではない。
 143 .BR mbrtowc (3)
 144 関数は
 145 同じ機能のより良いインターフェースを提供する。
 146 .\"O .SH "SEE ALSO"
 147 .SH 関連項目
 148 .BR MB_CUR_MAX (3),
 149 .BR mbrtowc (3),
 150 .BR mbstowcs (3)