.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Donn Seeley of BSDI.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)multibyte.3	8.1 (Berkeley) 6/4/93
.\"
.\" $FreeBSD$
.Dd June 4, 1993
.Dt MULTIBYTE 3
.Os
.Sh 名称
.Nm mblen ,
.Nm mbstowcs ,
.Nm mbtowc ,
.Nm wcstombs ,
.Nm wctomb
.Nd C 言語のマルチバイト文字サポート
.Sh 書式
.Fd #include <stdlib.h>
.Ft int
.Fn mblen "const char *mbchar" "size_t nbytes"
.Ft size_t
.Fn mbstowcs "wchar_t *wcstring" "const char *mbstring" "size_t nwchars"
.Ft int
.Fn mbtowc "wchar_t *wcharp" "const char *mbchar" "size_t nbytes"
.Ft size_t
.Fn wcstombs "char *mbstring" "const wchar_t *wcstring" "size_t nbytes"
.Ft int
.Fn wctomb "char *mbchar" "wchar_t wchar"
.Sh 解説
中国語のような自然言語の基本要素は、C 言語の
.Va char
型ひとつでは一意に表現できません。
標準 C 言語規格では、ワイド文字とマルチバイト文字
という、自然言語のエンコード方法の拡張を扱う 2 つの方法がサポート
されています。ワイド文字は、
基本要素ひとつひとつを型
.Va wchar_t
の単一オブジェクトにマップできるような内部表現です。マルチバイト文字は
入出力で使用され、C 言語の
.Va char
型のシーケンスとして基本要素ひとつひとつをコード化します。
マルチバイト文字では、個々の基本要素は、
1 バイト以上
.Pq Dv MB_CHAR_MAX バイトまで
にマップされます。
.Pp
ワイド文字とマルチバイト文字の解釈を支配するのは、カレントロケール
.Pq Xr setlocale 3
です。ロケールカテゴリ
.Dv LC_CTYPE
の指定によりこの解釈を制御します。
型
.Va wchar_t
は、すべてのロケールでのワイドキャラクタ表現の最大値を
十分収容できるだけの大きさを持ちます。
.Pp
マルチバイト文字列には、指定された表現方式の中で規定されるモード間での
切り替えを行なう
.Sq シフト
インジケータが含まれることがあります。シフトの発生を表すバイト列を
使用すると、これらのバイトは別の文字と見なされずに、それと隣接する
文字と一緒にまとめられます。
.Sq 初期
シフト状態は常に存在します。
関数
.Fn mbstowcs
と
.Fn wcstombs
は、マルチバイト文字列が初期シフト状態から解釈されるべきと想定します。
関数
.Fn mblen ,
.Fn mbtowc ,
.Fn wctomb
は、内部で静的シフト状態を維持管理します。
ポインタ
.Fa mbchar
が
.Dv NULL
である呼び出しでは、カレントロケールがシフト状態を必要とする場合は
ゼロ以外が戻されます。シフト状態を必要としない場合はゼロが戻されます。
シフト状態を必要とする場合、シフト状態は初期状態にリセットされます。
.Dv LC_CTYPE
か
.Dv LC_ALL
カテゴリを指定して
.Fn setlocale
を呼び出した後では、内部シフト状態は未定義になります。
.Pp
処理に便利なように、値が 0 のワイド文字
.Pq ナルワイド文字
は、ワイド文字列のターミネータとして認識されます。値が 0 の文字
.Pq  ナルバイト
は、マルチバイト文字列のターミネータとして認識されます。
マルチバイト文字では、ナルバイトが許可されていません。
.Pp
関数
.Fn mblen
は、マルチバイト文字
.Fa mbchar
のバイト長を算出します。
.Fa nbytes
バイトまでが検査されます。
.Pp
関数
.Fn mbtowc
は、マルチバイト文字
.Fa mbchar
をワイド文字に
変換し、その結果を
.Fa wcharp
が指すオブジェクトに格納します。
.Fa nbytes
バイトまでが検査されます。
.Pp
関数
.Fn wctomb
は、ワイド文字
.Fa wchar
をマルチバイト文字に
変換し、その結果を
.Fa mbchar
に格納します。
.Fa mbchar
が指すオブジェクトは、
そのマルチバイト文字を収容できるだけの大きさを持たねばなりません。
.Pp
関数
.Fn mbstowcs
は、マルチバイト文字列
.Fa mbstring
をワイド文字列
.Fa wcstring
に変換します。
.Fa nwchars
以上のワイド文字は格納されません。最後のナルワイド文字は、空きが
ある場合に追加されます。
.Pp
関数
.Fn wcstombs
は、ワイド文字列
.Fa wcstring
をマルチバイト文字列
.Fa mbstring
に変換します。
.Fa nbytes
バイトまでが
.Fa mbstring
に格納されます。文字列の最後の断片的なマルチバイト文字は格納されません。
マルチバイト文字列は、空きがあればナルバイトで終わります。
.Sh 戻り値
カレントロケールがマルチバイト文字がサポートしていない場合、
これらすべての関数は、文字を処理できる場合は -1 を戻し、
処理できない場合は 0 を戻します。
.Pp
.Fa mbchar
が
.Dv NULL
である場合、
関数
.Fn mblen ,
.Fn mbtowc ,
.Fn wctomb
は、シフト状態がサポートされている場合は 0 以外を戻し、
シフト状態がサポートされていない場合は 0 を戻します。
.Fa mbchar
が有効であると、この関数は
.Fa mbchar
で処理されたバイト数を戻します。マルチバイト文字を認識できない場合か
変換できない場合は -1 を戻します。
.Pp
.Fn mbstowcs
関数は、変換されたワイド文字数を戻します。最後の
ナルワイド文字は数に含めません。
.Fn wcstombs
関数は、変換されたバイト数を戻します。最後の
ナルバイトは数に含めません。不正なマルチバイト文字があると、
どちらの関数も -1 を戻します。
.Sh 関連項目
.Xr mbrune 3 ,
.Xr rune 3 ,
.Xr setlocale 3 ,
.Xr euc 4 ,
.Xr utf2 4
.Sh 規格
関数
.Fn mblen ,
.Fn mbstowcs ,
.Fn mbtowc ,
.Fn wcstombs ,
.Fn wctomb
は、
.St -ansiC
に準拠しています。
.Sh バグ
現在のシステムは、シフト状態をサポートしません。
.\"kuma 1999-11-12